Skip to content

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 />&rarr; {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.

Image

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

Image

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.