6. Internacionalização
6.1. Exemplo 21: uma aplicação bilíngue
[React] não tem um sistema de tradução. A biblioteca mais utilizada é a [i18next], que se liga ao [React] por meio da [react-i18next].
6.1.1. Os dicionários
| {
"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:"
}
}
|
Cada texto tem uma chave formada por nomes aninhados: [HOME.HELLO]. São os mesmos dicionários das lições anteriores, com duas particularidades do [i18next]:
- os parâmetros são escritos como [{{name}}]; um parâmetro pode ser formatado de acordo com o idioma: [{{date, datetime(dateStyle: full)}}] (uma data, com as opções de [Intl.DateTimeFormat]), [{{price, currency(EUR)}}] (um valor em euros);
- plurais: [i18next] seleciona automaticamente a forma com base no parâmetro [count] e nas regras do idioma: [APPOINTMENTS_one] ou [APPOINTMENTS_other], e [APPOINTMENTS_zero] para zero, se existir. O polonês, o árabe e outros idiomas têm formas diferentes ([_few], [_many]), que o [i18next] reconhece.
6.1.2. A configuração
| // =========================================================================
// 21-i18n/src/i18n/i18n.ts - a configuração do i18next
// -------------------------------------------------------------------------
// O i18next é a biblioteca de tradução mais usada em JavaScript;
// o react-i18next a liga ao React. Fornecemos a ele:
// - um DICIONÁRIO por idioma (fr.json, en.json), em que cada texto tem uma
// CHAVE ("HOME.HELLO"); os parâmetros se escrevem {{name}};
// {{date, datetime(...)}} e {{price, currency(EUR)}} formatam
// uma data ou um valor conforme o idioma (com a API Intl);
// - o idioma inicial (o guardado no localStorage, senão o do
// navegador, senão o inglês) e o idioma de fallback.
// Em um componente, t('HOME.HELLO', { name: 'Marie' }) dá o texto
// do idioma ATUAL; trocar o idioma chama de novo os componentes que
// usam t, e a página inteira é traduzida novamente.
//
// É, no lado do cliente, o mesmo princípio do curso de NestJS (dicionários
// i18n/*.json + helper {{t}}) - mas a tradução agora é feita no
// navegador, e trocar o idioma não exige mais nada do servidor.
// =========================================================================
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';
}
// a cada troca de idioma: ele é guardado, e o atributo lang
// da página é atualizado (útil para leitores de tela, para corretores ortográficos)
i18n.on('languageChanged', (language) => {
localStorage.setItem(LANGUAGE_KEY, language);
document.documentElement.lang = language;
});
// use(initReactI18next): o i18next notifica o React das trocas de idioma
i18n.use(initReactI18next).init({
// os dicionários fazem parte do código da aplicação: nenhuma requisição
resources: { fr: { translation: fr }, en: { translation: en } },
lng: initialLanguage(),
fallbackLng: 'en', // uma chave ausente em francês: usa-se a inglesa
// O React já faz o escape de tudo que exibe: o i18next não precisa fazê-lo
interpolation: { escapeValue: false },
});
export default i18n;
|
- linhas 23–24: os dicionários fazem parte do código da aplicação: são módulos JSON, importados como objetos ([resolveJsonModule], veja [tsconfig.json]);
- linhas 30–36: o idioma de origem: o armazenado em [localStorage]; caso contrário, francês se o idioma do navegador for o francês; caso contrário, inglês;
- linhas 40–43: a cada mudança de idioma, ele é armazenado e o atributo [lang] da página é atualizado (útil para leitores de tela e corretores ortográficos);
- linhas 46–53: a configuração: os dicionários ([translation] é o nome do espaço de chaves padrão), o idioma de origem, o idioma de reserva (se uma chave estiver ausente em francês, usa-se o inglês) e [escapeValue: false]: o [React] já faz o escape de tudo o que exibe.
| // =========================================================================
// 21-i18n/src/main.tsx - importar i18n/i18n.ts basta para configurar o i18next,
// antes da primeira exibição
// =========================================================================
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>,
);
|
Importar [i18n/i18n.ts] basta para configurar o [i18next] antes da primeira exibição.
6.1.3. A página traduzida
| // =========================================================================
// 21-i18n/src/App.tsx - uma página traduzida
// -------------------------------------------------------------------------
// - const { t, i18n } = useTranslation(): a função de tradução e
// o objeto i18next (i18n.language: o idioma atual);
// - t('KEY') um texto;
// - t('KEY', { name: ... }) um texto com parâmetros;
// - t('KEY', { count: n }) um texto no plural: o i18next escolhe
// a chave KEY_zero, KEY_one ou KEY_other;
// - i18n.changeLanguage('fr') troca o idioma: a página inteira é
// traduzida novamente.
// =========================================================================
import { useEffect, useState } from 'react';
import { useTranslation } from 'react-i18next';
import { LANGUAGES } from './i18n/i18n';
// o que o servidor RdvMedecins retornaria (cf. capítulo sobre a caixa-preta)
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());
// o título da aba acompanha o idioma
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>
{/* a data e o valor são formatados pelo dicionário, no idioma atual */}
<p>{t('HOME.TODAY', { date: today })}</p>
<p>{t('HOME.PRICE', { price: 1234.5 })}</p>
{/* count: escolhe a forma do plural e substitui {{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) => (
// a chave do servidor É uma chave do dicionário; params fornece seus parâmetros
<li key={r.key}>
<code>{r.statusCode} {r.key}</code>
<br />→ {t(r.key, r.params)}
</li>
))}
</ul>
</div>
</div>
);
}
|
- Linha 25: o hook do [react-i18next]: [t], a função de tradução, e [i18n], o objeto do [i18next] ([i18n.language] é o idioma atual). O componente é chamado novamente quando o idioma muda;
- linhas 30–32: o título da aba acompanha o idioma: a função [t] muda com o idioma;
- linha 41: troca de idioma: a página inteira é traduzida novamente sem fazer nenhuma requisição ao servidor;
- linha 49: texto com parâmetros;
- linhas 51–52: uma data e um valor, formatados pelo dicionário no idioma atual;
- linha 54: uma forma plural;
- linha 71: a chave enviada pelo servidor [RdvMedecins] É uma chave do dicionário (veja o próximo capítulo); [params] fornece seus parâmetros.

Em inglês, após a remoção de duas consultas:

No lado do cliente, o princípio é o mesmo do curso de [NestJS] (dicionários [i18n/*.json] + helper [{{t}}]); no entanto, a tradução agora ocorre no navegador, e a troca de idioma não exige mais nenhuma interação com o servidor.