Skip to content

6. Internacionalización

6.1. Ejemplo 21: una aplicación bilingüe

[React] no tiene un sistema de traducción. La biblioteca más utilizada es [i18next], que se vincula con [React] mediante [react-i18next].

6.1.1. Diccionarios

{
  "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 tiene una clave formada por nombres anidados: [HOME.HELLO]. Son los mismos diccionarios que en las lecciones anteriores, con dos particularidades de [i18next]:

  • los parámetros se escriben como [{{name}}]; un parámetro se puede formatear según el idioma: [{{date, datetime(dateStyle: full)}}] (una fecha, con las opciones de [Intl.DateTimeFormat]), [{{price, currency(EUR)}}] (un monto en euros);
  • plurales: [i18next] selecciona automáticamente la forma según el parámetro [count] y las reglas del idioma: [APPOINTMENTS_one] o [APPOINTMENTS_other], y [APPOINTMENTS_zero] para cero, si existe. El polaco, el árabe y otros idiomas tienen formas distintas ([_few], [_many]), que [i18next] reconoce.

6.1.2. La configuración

// =========================================================================
// 21-i18n/src/i18n/i18n.ts - la configuración de i18next
// -------------------------------------------------------------------------
// i18next es la biblioteca de traducción más usada en JavaScript;
// react-i18next la vincula con React. Le proporcionamos:
//   - un DICCIONARIO por idioma (fr.json, en.json), donde cada texto tiene una
//     CLAVE ("HOME.HELLO"); los parámetros se escriben {{name}};
//     {{date, datetime(...)}} y {{price, currency(EUR)}} formatean
//     una fecha o un monto según el idioma (con la API Intl);
//   - el idioma inicial (el almacenado en localStorage, si no el
//     del navegador, si no inglés) y el idioma de respaldo.
// En un componente, t('HOME.HELLO', { name: 'Marie' }) da el texto
// del idioma ACTUAL; cambiar el idioma vuelve a llamar a los componentes que
// usan t, y toda la página se traduce de nuevo.
//
// Es, en el lado del cliente, el mismo principio que el curso de NestJS (diccionarios
// i18n/*.json + helper {{t}}), pero la traducción ahora se hace en
// el navegador, y cambiar el idioma ya no le pide nada al 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';
}

// en cada cambio de idioma: se almacena y se actualiza el atributo lang
// de la página (útil para los lectores de pantalla y los correctores ortográficos)
i18n.on('languageChanged', (language) => {
  localStorage.setItem(LANGUAGE_KEY, language);
  document.documentElement.lang = language;
});

// use(initReactI18next): i18next notifica a React los cambios de idioma
i18n.use(initReactI18next).init({
  // los diccionarios forman parte del código de la aplicación: ninguna solicitud
  resources: { fr: { translation: fr }, en: { translation: en } },
  lng: initialLanguage(),
  fallbackLng: 'en', // una clave que falta en francés: se usa la inglesa
  // React ya escapa todo lo que muestra: i18next no tiene que hacerlo
  interpolation: { escapeValue: false },
});

export default i18n;
  • líneas 23–24: los diccionarios forman parte del código de la aplicación: son módulos JSON, importados como objetos ([resolveJsonModule], véase [tsconfig.json]);
  • líneas 30–36: el idioma de origen: el almacenado en [localStorage]; si no hay ninguno, francés si el idioma del navegador es el francés, y si no, inglés;
  • líneas 40–43: cada vez que cambia el idioma, este se almacena y se actualiza el atributo [lang] de la página (útil para los lectores de pantalla y los correctores ortográficos);
  • líneas 46–53: la configuración: los diccionarios ([translation] es el nombre del espacio de claves predeterminado), el idioma de origen, el idioma de respaldo (si falta una clave en francés, se usa el inglés) y [escapeValue: false]: [React] ya escapa todo lo que muestra.
// =========================================================================
// 21-i18n/src/main.tsx - importar i18n/i18n.ts basta para configurar i18next,
// antes de la primera visualización
// =========================================================================

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>,
);

Basta con importar [i18n/i18n.ts] para configurar [i18next] antes de la primera visualización.

6.1.3. La página traducida

// =========================================================================
// 21-i18n/src/App.tsx - una página traducida
// -------------------------------------------------------------------------
//   - const { t, i18n } = useTranslation(): la función de traducción y
//     el objeto i18next (i18n.language: el idioma actual);
//   - t('KEY')                        un texto;
//   - t('KEY', { name: ... })         un texto con parámetros;
//   - t('KEY', { count: n })          un texto en plural: i18next elige
//                                     la clave KEY_zero, KEY_one o KEY_other;
//   - i18n.changeLanguage('fr')       cambia el idioma: toda la página se
//                                     traduce de nuevo.
// =========================================================================

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

// lo que devolvería el servidor RdvMedecins (cf. capítulo sobre la caja negra)
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());

  // el título de la pestaña sigue al 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>
        {/* la fecha y el monto son formateados por el diccionario, en el idioma actual */}
        <p>{t('HOME.TODAY', { date: today })}</p>
        <p>{t('HOME.PRICE', { price: 1234.5 })}</p>
        {/* count: elige la forma plural y reemplaza {{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) => (
            // la clave del servidor ES una clave del diccionario; params proporciona sus parámetros
            <li key={r.key}>
              <code>{r.statusCode} {r.key}</code>
              <br />&rarr; {t(r.key, r.params)}
            </li>
          ))}
        </ul>
      </div>
    </div>
  );
}
  • Línea 25: el hook de [react-i18next]: [t], la función de traducción, e [i18n], el objeto [i18next] ([i18n.language] es el idioma actual). El componente se vuelve a llamar cuando cambia el idioma;
  • líneas 30–32: el título de la pestaña sigue al idioma: la función [t] cambia con el idioma;
  • línea 41: cambio de idioma: toda la página se vuelve a traducir sin hacer ninguna solicitud al servidor;
  • línea 49: texto con parámetros;
  • líneas 51–52: una fecha y un monto, formateados por el diccionario en el idioma actual;
  • línea 54: una forma plural;
  • línea 71: la clave enviada por el servidor [RdvMedecins] ES una clave del diccionario (véase el capítulo siguiente); [params] proporciona sus parámetros.

Image

En inglés, tras eliminar dos citas:

Image

En el lado del cliente, funciona con el mismo principio que el curso de [NestJS] (diccionarios [i18n/*.json] + auxiliar [{{t}}]); sin embargo, ahora la traducción ocurre en el navegador, y cambiar de idioma ya no requiere ninguna interacción con el servidor.