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 />→ {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] 提供它的参数。

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

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