Skip to content

6. Internacionalización

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

La aplicación [RdvMedecins] está disponible en francés e inglés. En el curso de [NestJS], el servidor traducía las páginas antes de enviarlas. Ahora, las páginas se generan en el navegador: el cliente las traduce, y cambiar de idioma ya no requiere ninguna interacción con el servidor.

[Angular] tiene su propio sistema de traducción, [@angular/localize], que genera una aplicación compilada para cada idioma: por lo tanto, cambiar de idioma consiste simplemente en cargar otra aplicación. En su lugar, usaremos la biblioteca [ngx-translate], la más utilizada junto con [Angular], que traduce en tiempo de ejecución: basta un solo clic para volver a traducir toda la página.

1
2
3
4
5
6
7
8
21-i18n/src/app/
├── i18n/
│   ├── fr.json          the French dictionary
│   ├── en.json          the English dictionary
│   ├── i18n.ts          the configuration of ngx-translate
│   └── plural.pipe.ts   the choice of the plural
├── app.ts
└── app.html

La biblioteca se declara en el archivo [package.json] del espacio de trabajo:

        "@ngx-translate/core": "^18.0.0",

6.1.1. Diccionarios

{
  "APP": {
    "TITLE": "Exemple 21 - une application en deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date}}.",
    "PRICE": "Une consultation coûte {{price}}.",
    "APPOINTMENTS": {
      "zero": "aucun rendez-vous",
      "one": "un rendez-vous",
      "other": "{{n}} 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}}.",
    "PRICE": "A consultation costs {{price}}.",
    "APPOINTMENTS": {
      "zero": "no appointment",
      "one": "one appointment",
      "other": "{{n}} 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 los nombres de los niveles sucesivos: [HOME.HELLO], [ERRORS.LOGIN_TAKEN]... El código y las plantillas ya no contienen ningún texto, solo claves;
  • línea 7: los parámetros se escriben entre dobles llaves: [{{name}}];
  • líneas 10–14: las formas plurales, agrupadas bajo la misma clave (véase más abajo);
  • líneas 18–21: las claves [ERRORS.*] son las que devuelve el servidor [RdvMedecins] en sus respuestas de error (próximo capítulo). El servidor no devuelve texto, sino una clave; el cliente la traduce al idioma del usuario.

6.1.2. La configuración

// =========================================================================
// 21-i18n/src/app/i18n/i18n.ts - la configuración de ngx-translate
// -------------------------------------------------------------------------
// ngx-translate es la biblioteca de traducción más utilizada con
// Angular. Le proporcionamos:
//   - un DICCIONARIO por idioma (fr.json, en.json), donde cada texto tiene una
//     CLAVE ("HOME.HELLO"); los parámetros se escriben {{name}};
//   - un LOADER (TranslateLoader), que devuelve el diccionario de un
//     idioma. El nuestro los toma del código de la aplicación (importación de
//     archivos JSON); otro podría descargarlos;
//   - el idioma inicial (el guardado en localStorage, si no el del
//     navegador, si no inglés) y el idioma de respaldo.
// En las plantillas, {{ 'HOME.HELLO' | translate: { name: 'Marie' } }}
// muestra el texto del idioma ACTUAL; cambiar de idioma actualiza
// toda la página.
//
// Es, del lado del cliente, el mismo principio que el curso de NestJS (diccionarios
// i18n/*.json + helper {{t}}) - pero la traducción se hace ahora en
// el navegador, y cambiar de idioma ya no le pide nada al servidor.
//
// (Angular también tiene su propio sistema, @angular/localize, que genera UNA
// aplicación compilada por idioma: el idioma solo se puede cambiar
// cambiando de página. ngx-translate, en cambio, traduce en tiempo de ejecución.)
// =========================================================================

import { Provider } from '@angular/core';
import { provideTranslateLoader, provideTranslateService, TranslateLoader, TranslationObject } from '@ngx-translate/core';
import { Observable, of } from 'rxjs';
import fr from './fr.json';
import en from './en.json';

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

// el loader de los diccionarios
class DictionariesLoader implements TranslateLoader {
  getTranslation(language: string): Observable<TranslationObject> {
    return of(language === 'en' ? en : fr);
  }
}

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

export function provideI18n(): Provider[] {
  return provideTranslateService({
    loader: provideTranslateLoader(DictionariesLoader),
    fallbackLang: 'en', // una clave ausente en francés: se usa la inglesa
    lang: initialLanguage(),
  });
}
  • Líneas 29–30: los diccionarios se importan como módulos; forman parte del código de la aplicación. Esto es posible gracias a la opción [resolveJsonModule] del archivo [tsconfig.json];
  • línea 34: la clave bajo la cual se almacena el idioma seleccionado en [localStorage] (ejemplo 20);
  • líneas 37–41: el cargador de diccionarios: [ngx-translate] lo llama para obtener el diccionario de un idioma en forma de observable. El nuestro los obtiene del código; otro podría descargarlos del servidor;
  • líneas 43–49: el idioma de origen: el que el usuario seleccionó por última vez; si no, francés si el idioma del navegador es el francés; si no, inglés;
  • líneas 51–57: [provideTranslateService] pone los servicios de [ngx-translate] a disposición de toda la aplicación. [fallbackLang]: el idioma que se usa para una clave ausente del diccionario actual.
// =========================================================================
// 21-i18n/src/main.ts
// -------------------------------------------------------------------------
// provideI18n(): ngx-translate (ver app/i18n/i18n.ts).
// registerLocaleData(localeFr): las reglas francesas de los pipes de fecha,
// moneda... (el inglés siempre está disponible).
// =========================================================================

import { registerLocaleData } from '@angular/common';
import localeFr from '@angular/common/locales/fr';
import { bootstrapApplication } from '@angular/platform-browser';
import { App } from './app/app';
import { provideI18n } from './app/i18n/i18n';

registerLocaleData(localeFr);

bootstrapApplication(App, { providers: [provideI18n()] }).catch((error) => console.error(error));
  • línea 15: los pipes [date] y [currency] (ejemplo 09) conocen las reglas del inglés; las del francés deben registrarse;
  • línea 17: los servicios de [ngx-translate] se agregan a la aplicación.

6.1.3. Plurales

[ngx-translate] no admite plurales. Un pequeño pipe selecciona la forma correcta:

// =========================================================================
// 21-i18n/src/app/i18n/plural.pipe.ts - elegir la forma plural
// -------------------------------------------------------------------------
// ngx-translate no maneja los plurales. El diccionario da las
// formas bajo una misma clave ("APPOINTMENTS": { "zero", "one", "other" }) y
// este pipe elige la correcta, según el número y el idioma:
//     {{ 'HOME.APPOINTMENTS' | plural: n : language | translate: { n } }}
// Intl.PluralRules conoce las reglas de cada idioma ("one" u "other" en
// inglés como en francés, pero otras formas en polaco, en árabe...).
// =========================================================================

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({ name: 'plural' })
export class PluralPipe implements PipeTransform {
  transform(key: string, n: number, language: string | null): string {
    if (n === 0) {
      return `${key}.zero`;
    }
    return `${key}.${new Intl.PluralRules(language ?? 'en').select(n)}`;
  }
}
  • Líneas 16–21: el pipe recibe una clave ([HOME.APPOINTMENTS]), un número y un idioma; devuelve la clave en la forma correcta ([HOME.APPOINTMENTS.one], por ejemplo);
  • Línea 18: el cero tiene su propio formato (“no appointment”);
  • línea 20: [Intl.PluralRules], proporcionado por el navegador, sigue las reglas de cada idioma: [one] u [other] en francés e inglés, pero otras formas en polaco o árabe. (Nota: en francés, 1,5 es singular; en inglés, es plural.)

6.1.4. La página traducida

// =========================================================================
// 21-i18n/src/app/app.ts - una página traducida
// -------------------------------------------------------------------------
//   - 'KEY' | translate                    un texto;
//   - 'KEY' | translate: { name: ... }     un texto con parámetros;
//   - date / currency con el idioma       una fecha, un monto, en el formato
//                                          del idioma actual;
//   - translate.use('fr')                  cambia el idioma: toda la
//                                          página se traduce de nuevo.
// TranslateService.currentLang es un SIGNAL: el idioma actual.
// =========================================================================

import { Component, effect, inject, signal } from '@angular/core';
import { CurrencyPipe, DatePipe } from '@angular/common';
import { TranslatePipe, TranslateService } from '@ngx-translate/core';
import { LANGUAGE_KEY, Language, LANGUAGES } from './i18n/i18n';
import { PluralPipe } from './i18n/plural.pipe';

@Component({
  selector: 'app-root',
  imports: [CurrencyPipe, DatePipe, TranslatePipe, PluralPipe],
  templateUrl: './app.html',
})
export class App {
  private readonly translate = inject(TranslateService);
  protected readonly language = this.translate.currentLang;
  protected readonly languages = LANGUAGES;
  protected readonly count = signal(2);
  protected readonly today = new Date();

  // lo que devolvería el servidor RdvMedecins (ver el capítulo sobre la caja negra)
  protected readonly serverResponses = [
    { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
    { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
  ];

  // translate.translate(key): un SIGNAL que sigue el idioma actual
  private readonly title = this.translate.translate('APP.TITLE');

  constructor() {
    // en cada cambio de idioma: lo guardamos y actualizamos
    // el atributo lang de la página (útil para los lectores de pantalla y los correctores ortográficos)
    effect(() => {
      const language = this.language();
      if (language) {
        localStorage.setItem(LANGUAGE_KEY, language);
        document.documentElement.lang = language;
      }
      document.title = String(this.title());
    });
  }

  protected choose(language: Language): void {
    this.translate.use(language);
  }
}
  • línea 21: [TranslatePipe]: el pipe [translate];
  • línea 25: [TranslateService]: el servicio principal de [ngx-translate];
  • línea 26: [currentLang]: el idioma actual, como signal;
  • líneas 32–35: dos respuestas de error, tal como las devolvería el servidor: una clave y parámetros;
  • línea 38: [translate.translate(key)] devuelve un signal igual a la traducción de la clave, que sigue al idioma actual;
  • líneas 43–50: una acción que se ejecuta cada vez que cambia el idioma: se almacena el idioma (línea 46), se actualiza el atributo [lang] de la página (línea 47; lo usan los lectores de pantalla y los correctores ortográficos), así como el título de la pestaña (línea 49);
  • línea 54: [use] cambia el idioma actual: toda la página se vuelve a traducir.
<div class="container py-4" style="max-width: 720px">
  <div class="d-flex justify-content-between align-items-center mb-3">
    <h1 class="h3 mb-0">{{ 'APP.TITLE' | translate }}</h1>
    <div class="btn-group btn-group-sm" role="group" [attr.aria-label]="'APP.LANGUAGE' | translate">
      @for (l of languages; track l) {
        <button class="btn" [class]="language() === l ? 'btn-primary' : 'btn-outline-primary'" (click)="choose(l)">
          {{ l.toUpperCase() }}
        </button>
      }
    </div>
  </div>

  <div class="card p-3 mb-3">
    <p>{{ 'HOME.HELLO' | translate: { name: 'Marie' } }}</p>
    <!-- un parámetro calculado por otro pipe, en el idioma actual -->
    <p>{{ 'HOME.TODAY' | translate: { date: (today | date: 'fullDate' : '' : language() ?? 'en') } }}</p>
    <p>{{ 'HOME.PRICE' | translate: { price: (1234.5 | currency: 'EUR' : 'symbol' : '1.2-2' : language() ?? 'en') } }}</p>
    <!-- plural elige la clave (zero, one, other), translate la traduce -->
    <p class="fw-bold">{{ 'HOME.APPOINTMENTS' | plural: count() : language() | translate: { n: count() } }}</p>
    <div class="d-flex gap-2">
      <button class="btn btn-sm btn-outline-success" (click)="count.set(count() + 1)">{{ 'HOME.ADD' | translate }}</button>
      <button class="btn btn-sm btn-outline-secondary" [disabled]="count() === 0" (click)="count.set(count() - 1)">
        {{ 'HOME.REMOVE' | translate }}
      </button>
    </div>
  </div>

  <div class="card p-3">
    <h2 class="h6">{{ 'SERVER.TITLE' | translate }}</h2>
    <p>{{ 'SERVER.EXPLANATION' | translate }}</p>
    <ul class="mb-0">
      @for (r of serverResponses; track r.key) {
        <!-- la clave del servidor ES una clave del diccionario; params proporciona sus parámetros -->
        <li><code>{{ r.statusCode }} {{ r.key }}</code><br>&rarr; {{ r.key | translate: r.params }}</li>
      }
    </ul>
  </div>
</div>
  • línea 3: ['APP.TITLE' | translate]: la traducción de la clave en el idioma actual;
  • línea 6: el botón del idioma actual aparece resaltado;
  • línea 14: un texto con parámetros: el pipe recibe un objeto que proporciona el valor de cada parámetro;
  • líneas 16–17: el valor de un parámetro puede calcularlo otro pipe. El último argumento de [date] y [currency] es el idioma: la fecha y el importe se escriben al estilo francés o inglés;
  • línea 19: dos pipes encadenados: [plural] selecciona la clave y [translate] la traduce;
  • línea 34: la clave devuelta por el servidor se traduce, junto con sus parámetros.

[npm start 21-i18n]; con un navegador configurado en francés, la página aparece en francés:

Image

Haga clic en [EN]y luego en “Remove one”:

Image

Recargue la página: sigue en inglés; el idioma se ha guardado.