博客Dashboard

切换语言

如何在 React 应用中配置并切换语言

语言切换允许用户选择其偏好的 locale，用于展示应用内容。GT React 提供多种方式，从简单的代码方式切换到用于自定义语言选择器的预构建 UI 组件。

可用方法

使用 useSetLocale 钩子

useSetLocale 钩子用于切换应用的语言：

import { useSetLocale } from 'gt-react';

export default function MyComponent() {
  const setLocale = useSetLocale();

  return <button onClick={() => setLocale('en')}>设置语言环境</button>;
}

只需将要切换的 locale 作为参数传给该 hook 返回的函数即可。

使用 <LocaleSelector> 组件

<LocaleSelector> 组件提供了一个开箱即用的下拉菜单，会自动显示所有已配置的 locales：

import { LocaleSelector } from 'gt-react';

export default function MyComponent() {
  return <LocaleSelector />;
}

该组件会自动：

  • 显示项目中配置的所有 locale
  • 以各自的本地语言名称显示 locale
  • 处理切换逻辑
  • 维护当前选择状态

使用 useLocaleSelector 钩子

如果你想构建自己的自定义 locale 选择器组件，请使用 useLocaleSelector：

import { useLocaleSelector } from 'gt-react';

function CustomLocaleSelector() {
  const { 
    locale,              // 当前生效的 locale（如 'en'、'es'）
    locales,             // 项目支持的 locale 数组 ['en', 'es', 'fr']
    setLocale,           // 更改 locale 的函数：setLocale('es')
    getLocaleProperties  // 获取某个 locale 显示信息的函数
  } = useLocaleSelector();
  
  if (!locales?.length) return null;
  
  return (
    <select 
      value={locale || ''} 
      onChange={(e) => setLocale(e.target.value)}
    >
      {locales.map((loc) => {
        const props = getLocaleProperties(loc);
        return (
          <option key={loc} value={loc}>
            {props.nativeNameWithRegionCode} {/* 例如："English (US)"、"Español (ES)" */}
          </option>
        );
      })}
    </select>
  );
}

重要注意事项

GTProvider 要求

语言切换组件必须在 <GTProvider> 内使用：

// ✅ 正确
<GTProvider>
  <LanguageSwitcher />
</GTProvider>

// ❌ 错误——在 Provider 外部
<LanguageSwitcher />

下一步

本指南如何?

Dictionaries

如何使用传统的基于字典的翻译模式

本地翻译存储

将翻译随应用一同打包，而非通过内容分发网络（CDN）提供

本页目录

可用方法
使用 useSetLocale 钩子
使用 <LocaleSelector> 组件
使用 useLocaleSelector 钩子
重要注意事项
GTProvider 要求
下一步