Skip to content

6. 国际化

6.1. 示例 21:双语应用

[React] 没有翻译系统。最常用的库是 [i18next],它通过 [react-i18next] 与 [React] 连接。

6.1.1. 词典

{
  "APP": {
    "TITLE": "Exemple 21 - une application en deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date, datetime(dateStyle: full)}}.",
    "PRICE": "Une consultation coûte {{price, currency(EUR)}}.",
    "APPOINTMENTS_zero": "aucun rendez-vous",
    "APPOINTMENTS_one": "un rendez-vous",
    "APPOINTMENTS_other": "{{count}} rendez-vous",
    "ADD": "Ajouter un rendez-vous",
    "REMOVE": "En retirer un"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "Ce login est déjà utilisé par un autre compte.",
    "TOO_MANY_ATTEMPTS": "Trop de tentatives infructueuses. Réessayez dans {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Traduire une réponse du serveur",
    "EXPLANATION": "Le serveur RdvMedecins ne renvoie que des clés. C'est le client qui les traduit :"
  }
}
{
  "APP": {
    "TITLE": "Example 21 - a two-language application",
    "LANGUAGE": "Language"
  },
  "HOME": {
    "HELLO": "Hello {{name}}!",
    "TODAY": "Today is {{date, datetime(dateStyle: full)}}.",
    "PRICE": "A consultation costs {{price, currency(EUR)}}.",
    "APPOINTMENTS_zero": "no appointment",
    "APPOINTMENTS_one": "one appointment",
    "APPOINTMENTS_other": "{{count}} appointments",
    "ADD": "Add an appointment",
    "REMOVE": "Remove one"
  },
  "ERRORS": {
    "LOGIN_TAKEN": "This login is already used by another account.",
    "TOO_MANY_ATTEMPTS": "Too many failed attempts. Try again in {{minutes}} minute(s)."
  },
  "SERVER": {
    "TITLE": "Translating a server response",
    "EXPLANATION": "The RdvMedecins server only sends keys. The client translates them:"
  }
}

每段文本都有一个由嵌套名称组成的 键 :[HOME.HELLO]。这些词典与之前各课中的相同,只有 [i18next] 的两个特有之处:

  • 参数写作 [{{name}}];参数可以按语言格式化:[{{date, datetime(dateStyle: full)}}] (一个日期,选项来自 [Intl.DateTimeFormat])、[{{price, currency(EUR)}}] (欧元金额);
  • 复数:[i18next] 根据参数 [count] 和语言规则自动选择形式:[APPOINTMENTS_one] 或 [APPOINTMENTS_other],如果存在,数量为零时用 [APPOINTMENTS_zero]。波兰语、阿拉伯语和其他语言有不同的形式([_few]、[_many]),[i18next] 都能识别。

6.1.2. 配置

// =========================================================================
// 21-i18n/src/i18n/i18n.ts - i18next 的配置
// -------------------------------------------------------------------------
// i18next 是 JavaScript 中使用最广泛的翻译库;
// react-i18next 把它与 React 连接起来。我们向它提供:
//   - 每种语言一个字典(fr.json、en.json),其中每段文字都有一个
//     键("HOME.HELLO");参数写作 {{name}};
//     {{date, datetime(...)}} 和 {{price, currency(EUR)}} 会按语言格式化
//     日期或金额(借助 Intl API);
//   - 初始语言(保存在 localStorage 中的语言,否则取浏览器的语言
//     ,再否则取英语)以及回退语言。
// 在组件中,t('HOME.HELLO', { name: 'Marie' }) 会给出
// 当前语言的文字;切换语言会让使用 t 的组件重新被调用
// ,整个页面随之重新翻译。
//
// 在客户端,这与 NestJS 课程的原理相同(字典
// i18n/*.json + 辅助函数 {{t}}),只是现在翻译在
// 浏览器中完成,切换语言不再需要服务器做任何事。
// =========================================================================

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import fr from './fr.json';
import en from './en.json';

export type Language = 'fr' | 'en';
export const LANGUAGES: Language[] = ['fr', 'en'];
const LANGUAGE_KEY = 'example21.language';

function initialLanguage(): Language {
  const stored = localStorage.getItem(LANGUAGE_KEY);
  if (stored === 'fr' || stored === 'en') {
    return stored;
  }
  return navigator.language.startsWith('fr') ? 'fr' : 'en';
}

// 每次切换语言时:保存所选语言,并更新页面的 lang 属性
// (这对屏幕阅读器、拼写检查器很有用)
i18n.on('languageChanged', (language) => {
  localStorage.setItem(LANGUAGE_KEY, language);
  document.documentElement.lang = language;
});

// use(initReactI18next):i18next 把语言的变化通知给 React
i18n.use(initReactI18next).init({
  // 字典是应用代码的一部分:无需发起请求
  resources: { fr: { translation: fr }, en: { translation: en } },
  lng: initialLanguage(),
  fallbackLng: 'en', // 法语中缺少的键:使用英语的对应键
  // React 已经对显示的所有内容做了转义:i18next 无需再转义
  interpolation: { escapeValue: false },
});

export default i18n;
  • 第 23–24 行:词典是应用代码的一部分:它们是 JSON 模块,作为对象导入([resolveJsonModule],见 [tsconfig.json]);
  • 第 30–36 行:初始语言:优先取存放在 [localStorage] 中的语言,否则如果浏览器的语言是法语就用法语,否则用英语;
  • 第 40–43 行:每次语言变化时,都会保存它并更新页面的 [lang] 属性(对屏幕阅读器和拼写检查器有用);
  • 第 46–53 行:配置:词典([translation] 是默认键空间的名称)、初始语言、回退语言(如果某个键在法语中缺失,就使用英语),以及 [escapeValue: false]:[React] 已经对它显示的一切内容做了转义。
// =========================================================================
// 21-i18n/src/main.tsx - 导入 i18n/i18n.ts 就足以配置 i18next
// ,且发生在第一次渲染之前
// =========================================================================

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import 'bootstrap/dist/css/bootstrap.min.css';
import './i18n/i18n';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

只需导入 [i18n/i18n.ts] ,就足以在第一次显示之前配置好 [i18next]。

6.1.3. 翻译后的页面

// =========================================================================
// 21-i18n/src/App.tsx - 一个已翻译的页面
// -------------------------------------------------------------------------
//   - const { t, i18n } = useTranslation():翻译函数,以及
//     i18next 对象(i18n.language:当前语言);
//   - t('KEY')                        一段文字;
//   - t('KEY', { name: ... })         带参数的文字;
//   - t('KEY', { count: n })          复数形式的文字:i18next 会选择
//                                     键 KEY_zero、KEY_one 或 KEY_other;
//   - i18n.changeLanguage('fr')       切换语言:整个页面
//                                     重新翻译。
// =========================================================================

import { useEffect, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { LANGUAGES } from './i18n/i18n';

// RdvMedecins 服务器将返回的内容(参见黑盒一章)
const SERVER_RESPONSES = [
  { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
  { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
];

export default function App() {
  const { t, i18n } = useTranslation();
  const [count, setCount] = useState(2);
  const [today] = useState(() => new Date());

  // 标签页的标题随语言变化
  useEffect(() => {
    document.title = t('APP.TITLE');
  }, [t]);

  return (
    <div className="container py-4" style={{ maxWidth: 720 }}>
      <div className="d-flex justify-content-between align-items-center mb-3">
        <h1 className="h3 mb-0">{t('APP.TITLE')}</h1>
        <div className="btn-group btn-group-sm" role="group" aria-label={t('APP.LANGUAGE')}>
          {LANGUAGES.map((l) => (
            <button key={l} className={`btn ${i18n.language === l ? 'btn-primary' : 'btn-outline-primary'}`}
                    onClick={() => i18n.changeLanguage(l)}>
              {l.toUpperCase()}
            </button>
          ))}
        </div>
      </div>

      <div className="card p-3 mb-3">
        <p>{t('HOME.HELLO', { name: 'Marie' })}</p>
        {/* 日期和金额由字典按当前语言格式化 */}
        <p>{t('HOME.TODAY', { date: today })}</p>
        <p>{t('HOME.PRICE', { price: 1234.5 })}</p>
        {/* count:选择复数形式,并替换 {{count}} */}
        <p className="fw-bold">{t('HOME.APPOINTMENTS', { count })}</p>
        <div className="d-flex gap-2">
          <button className="btn btn-sm btn-outline-success" onClick={() => setCount(count + 1)}>{t('HOME.ADD')}</button>
          <button className="btn btn-sm btn-outline-secondary" disabled={count === 0} onClick={() => setCount(count - 1)}>
            {t('HOME.REMOVE')}
          </button>
        </div>
      </div>

      <div className="card p-3">
        <h2 className="h6">{t('SERVER.TITLE')}</h2>
        <p>{t('SERVER.EXPLANATION')}</p>
        <ul className="mb-0">
          {SERVER_RESPONSES.map((r) => (
            // 服务器返回的键本身就是字典中的一个键;params 提供它的参数
            <li key={r.key}>
              <code>{r.statusCode} {r.key}</code>
              <br />&rarr; {t(r.key, r.params)}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}
  • 第 25 行:[react-i18next] 的 Hook:[t] 是翻译函数,[i18n] 是 [i18next] 对象([i18n.language] 是当前语言)。语言变化时组件会被调用;
  • 第 30–32 行:标签页标题跟随语言:函数 [t] 随语言而变化;
  • 第 41 行:切换语言:整个页面被重新翻译,而无需向服务器发送任何请求;
  • 第 49 行:带参数的文本;
  • 第 51–52 行:日期和金额,由词典按当前语言格式化;
  • 第 54 行:复数形式;
  • 第 71 行:服务器 [RdvMedecins] 发送的键就是词典中的键(见下一章);[params] 提供它的参数。

Image

英文界面,删除两个预约之后:

Image

在客户端,它的工作原理与 [NestJS] 课程相同([i18n/*.json] 词典 + [{{t}}] 辅助函数);不过现在翻译发生在浏览器中,切换语言不再需要与服务器进行任何交互。