Skip to content

7. Internacionalización

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

Una aplicación bilingüe tiene tres tipos de texto que traducir:

  • el texto de la aplicación: etiquetas y mensajes. Se almacenan en diccionarios, uno por idioma;
  • las fechas y los importes: el objeto [Intl] de [JavaScript] los formatea en el idioma deseado (véase el Ejemplo 09);
  • el texto de [Ionic] mismo: los meses y días de su calendario, sus botones. El calendario ([<ion-datetime>]) recibe el idioma mediante su atributo [locale].

7.1.1. Los diccionarios

{
  "APP": {
    "TITLE": "Exemple 21 - deux langues",
    "LANGUAGE": "Langue"
  },
  "HOME": {
    "HELLO": "Bonjour {{name}} !",
    "TODAY": "Nous sommes le {{date}}.",
    "PRICE": "Une consultation coûte {{price}}.",
    "APPOINTMENTS_zero": "aucun rendez-vous",
    "APPOINTMENTS_one": "un rendez-vous",
    "APPOINTMENTS_other": "{{count}} rendez-vous",
    "ADD": "Ajouter un rendez-vous",
    "REMOVE": "En retirer un",
    "CALENDAR": "Ouvrir le calendrier",
    "CALENDAR_OK": "OK",
    "CALENDAR_CANCEL": "Annuler"
  },
  "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 :"
  }
}

Cada texto tiene una clave ("HOME.HELLO"). Los parámetros se escriben como [{{name}}]; un texto con plural tiene varias claves: [_zero], [_one], [_other]. Estas son las convenciones de la biblioteca [JavaScript] [i18next] , utilizada por los clientes [React] y [Vue.js] de [RdvMedecins]: el caso de estudio usará sus diccionarios, complementados con algunas claves adicionales. El diccionario en inglés tiene las mismas claves:

{
  "APP": {
    "TITLE": "Example 21 - two languages",
    "LANGUAGE": "Language"
  },
  "HOME": {
    "HELLO": "Hello {{name}}!",
    "TODAY": "Today is {{date}}.",
    "PRICE": "A consultation costs {{price}}.",
    "APPOINTMENTS_zero": "no appointment",
    "APPOINTMENTS_one": "one appointment",
    "APPOINTMENTS_other": "{{count}} appointments",
    "ADD": "Add an appointment",
    "REMOVE": "Remove one",
    "CALENDAR": "Open the calendar",
    "CALENDAR_OK": "OK",
    "CALENDAR_CANCEL": "Cancel"
  },
  "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:"
  }
}

Los archivos de la carpeta [public/] del proyecto se entregan tal cual con la aplicación (en un navegador: en la dirección /i18n/ex21-fr.json; en [Android]: dentro de la propia aplicación). En comparación con los diccionarios del ejemplo de [Flutter], se han agregado dos claves: [CALENDAR_OK] y [CALENDAR_CANCEL], que corresponden a los botones del calendario (se tratan más adelante).

7.1.2. Traducciones

// =========================================================================
// src/app/ex21-i18n/translations.ts - diccionarios, un idioma actual
// -------------------------------------------------------------------------
// Cada idioma tiene su DICCIONARIO, un archivo JSON incluido con
// la aplicación (public/i18n/ex21-fr.json, ex21-en.json), donde cada texto
// tiene una CLAVE ("HOME.HELLO"):
//   - t('HOME.HELLO', { name: 'Marie' }): el texto del idioma
//     ACTUAL, cuyos parámetros {{name}} se reemplazan;
//   - t('HOME.APPOINTMENTS', { count: n }): un texto en plural;
//     se elige la clave APPOINTMENTS_zero, _one u _other según n y las reglas
//     del idioma (en francés, 0 y 1 son singular; en inglés,
//     solo 1);
//   - changeLanguage('fr'): carga el otro diccionario. El idioma y el
//     diccionario son SEÑALES: las plantillas que llaman a t() se
//     actualizan, se traducen de nuevo.
// Estas son las convenciones de la biblioteca JavaScript i18next: los
// diccionarios son los de los clientes Vue.js, Angular y React de
// RdvMedecins... y el servidor, que solo devuelve CLAVES
// ("ERRORS.LOGIN_TAKEN"), también los usa.
// =========================================================================

import { signal } from '@angular/core';
import { Preferences as DeviceStorage } from '@capacitor/preferences';

export const languages = ['fr', 'en'];

// un diccionario: textos, u otros diccionarios (JSON anidado)
type Dictionary = { [key: string]: string | Dictionary };

export class Translations {
  private readonly _language = signal('en');
  private readonly _dictionary = signal<Dictionary>({});
  readonly language = this._language.asReadonly();

  // prefix: el inicio del nombre de los diccionarios (public/i18n/<prefix>-<language>.json)
  constructor(private readonly prefix: string) {}

  // el idioma inicial: el almacenado en el dispositivo; si no, el del
  // teléfono (si se conoce); si no, inglés
  async start(): Promise<void> {
    const stored = (await DeviceStorage.get({ key: `${this.prefix}.language` })).value;
    const device = navigator.language.substring(0, 2); // "en-US" -> "en"
    await this.changeLanguage(stored ?? (languages.includes(device) ? device : 'en'));
  }

  async changeLanguage(language: string): Promise<void> {
    // fetch: lee un archivo incluido con la aplicación (carpeta public/)
    const response = await fetch(`i18n/${this.prefix}-${language}.json`);
    this._dictionary.set((await response.json()) as Dictionary);
    this._language.set(language);
    // el idioma de la página (lectores de pantalla, separación silábica...)
    document.documentElement.lang = language;
    await DeviceStorage.set({ key: `${this.prefix}.language`, value: language });
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO']; undefined si no existe
  private find(key: string): string | undefined {
    let node: string | Dictionary | undefined = this._dictionary();
    for (const part of key.split('.')) {
      node = typeof node === 'object' ? node[part] : undefined;
    }
    return typeof node === 'string' ? node : undefined;
  }

  t(key: string, params: Record<string, string | number> = {}): string {
    let text: string | undefined;
    const count = params['count'];
    if (typeof count === 'number') {
      // Intl.PluralRules: la forma del plural ("one", "other"...), según las
      // reglas del idioma; la clave _zero, si existe, gana para 0
      const form = new Intl.PluralRules(this._language()).select(count);
      text = (count === 0 ? this.find(`${key}_zero`) : undefined) ?? this.find(`${key}_${form}`);
    }
    text ??= this.find(key);
    // una clave desconocida se muestra tal cual: se ve de inmediato lo que falta
    if (text === undefined) return key;
    // {{name}} -> el valor del parámetro name
    return text.replace(/\{\{(\w+)\}\}/g, (all, name: string) => String(params[name] ?? all));
  }
}
  • línea 25: los idiomas de la aplicación;
  • línea 28: el tipo de un diccionario: un objeto en el que cada propiedad es un texto u otro diccionario (el tipo es recursivo: se referencia a sí mismo);
  • líneas 30–33: las traducciones almacenan el idioma actual y su diccionario en variables. Una clase simple, no un servicio [@Injectable]: cada usuario la crea con su propio prefijo (línea 36; el Ejemplo 25 tendrá sus diccionarios, [ex25-fr.json]...). Se proporcionará a la página mediante una “fábrica” (se trata más adelante);
  • línea 36: [private readonly prefix] en los parámetros del constructor declara E inicializa un campo: un atajo de [TypeScript];
  • líneas 40–44: el idioma de origen: el almacenado en el dispositivo (el plugin [@capacitor/preferences] del Ejemplo 20); de lo contrario, el idioma del teléfono ([navigator.language]: “en-US”, de la cual se conservan las dos primeras letras), si se conoce; de lo contrario, inglés;
  • líneas 46–54: cambiar de idioma: leer el diccionario mediante [fetch], la función de [JavaScript] que lee una dirección (en este caso, un archivo incluido con la aplicación) y devuelve una [Promise] que representa la respuesta; decodificar su contenido JSON ([response.json()], otra [Promise]); almacenar el diccionario y el idioma en sus respectivos campos; actualizar el idioma de la página (el atributo [lang] de la etiqueta [<html>], útil para los lectores de pantalla); guardar la selección en el dispositivo. Habríamos podido usar el cliente HTTP de [Angular] (Ejemplo 22): [fetch] evita depender de él en una clase simple;
  • líneas 57–63: búsqueda de una clave “HOME.HELLO” en el diccionario: se desciende parte por parte ([split('.')]) a través de los objetos JSON anidados. [typeof node === 'object'] es una comprobación de tipo que “estrecha” el tipo de la variable en la rama donde es verdadera: [TypeScript] sabe entonces que [node] es un diccionario. Leer la signal ([this._dictionary()], línea 58) es esencial: una plantilla que llama a [t()] lee la signal de este modo y se actualizará cuando cambie el diccionario;
  • líneas 65–79: la traducción. Para un plural (un parámetro numérico [count]), [Intl.PluralRules] devuelve la forma plural según las reglas del idioma: [select(n)] da como resultado [one] u [other] (otros idiomas tienen también [two], [few], [many]). En francés, 0 y 1 son singular ([one]); en inglés, solo 1. La clave [_zero], si existe, tiene prioridad sobre 0 (línea 72), igual que con [i18next]. Una clave desconocida se muestra tal cual (línea 76): se ve de inmediato qué falta. Por último (línea 78), cada [{{name}}] se reemplaza por el valor del parámetro: una expresión regular, [/\{\{(\w+)\}\}/g], y una función que recibe cada coincidencia ([all]) y el nombre capturado entre paréntesis ([name]).

¿Por qué no usar la herramienta oficial de [Angular]? [Angular] tiene su propio sistema de internacionalización ([@angular/localize]): se marcan los textos de las plantillas ([<p i18n>Hello</p>]), se extraen las traducciones a archivos y la compilación produce UNA aplicación por cada idioma. Es la mejor solución para un sitio web en el que todo el texto se conoce de antemano. Sin embargo, no cambia de idioma “sobre la marcha”, y nuestro servidor devuelve claves (“ERRORS.LOGIN_TAKEN”) que deben traducirse en tiempo de ejecución: un diccionario, consultado por la clave, es mucho más adecuado para este fin y permite compartir diccionarios con otros clientes. También existen bibliotecas que hacen esto para [Angular] ([ngx-translate], [Transloco]): nuestro servicio es una versión mínima de ellas.

7.1.3. La página traducida

// =========================================================================
// src/app/ex21-i18n/ex21.page.ts - una aplicación en dos idiomas
// -------------------------------------------------------------------------
//   - los TEXTOS de la aplicación: los diccionarios (translations.ts),
//     proporcionados a la página por inyección de dependencias (providers);
//   - las fechas y los montos: el objeto Intl de JavaScript, en el
//     idioma actual (véase el ejemplo 09);
//   - los textos de Ionic MISMO (el calendario): el atributo locale
//     de <ion-datetime>, y sus botones, traducidos por nuestros diccionarios.
// Cambiar el idioma vuelve a traducir toda la pantalla, sin reiniciar.
// =========================================================================

import { Component, computed, effect, inject, signal } from '@angular/core';
import { Title } from '@angular/platform-browser';
import {
  IonBackButton, IonButton, IonButtons, IonCard, IonCardContent, IonCardHeader, IonCardSubtitle, IonContent,
  IonDatetime, IonHeader, IonIcon, IonLabel, IonModal, IonSegment, IonSegmentButton, IonTitle, IonToolbar,
  SegmentValue,
} from '@ionic/angular';
import { addIcons } from 'ionicons';
import { calendarOutline } from 'ionicons/icons';
import { languages, Translations } from './translations';

// lo que devolvería el servidor de RdvMedecins (véase el capítulo sobre la caja negra)
const serverResponses: { statusCode: number; key: string; params: Record<string, string> }[] = [
  { statusCode: 409, key: 'ERRORS.LOGIN_TAKEN', params: {} },
  { statusCode: 429, key: 'ERRORS.TOO_MANY_ATTEMPTS', params: { minutes: '15' } },
];

@Component({
  selector: 'app-ex21',
  imports: [
    IonHeader, IonToolbar, IonButtons, IonBackButton, IonTitle, IonSegment, IonSegmentButton, IonLabel, IonContent,
    IonCard, IonCardHeader, IonCardSubtitle, IonCardContent, IonButton, IonIcon, IonModal, IonDatetime,
  ],
  templateUrl: './ex21.page.html',
  // un proveedor ESPECÍFICO de la página: las traducciones de los diccionarios ex21-*.json
  providers: [{ provide: Translations, useFactory: () => new Translations('ex21') }],
  styles: `
    ion-segment { width: 110px; margin-inline-end: 8px; }
    ion-segment-button { min-width: 50px; }
    ion-modal.calendar { --width: fit-content; --height: fit-content; --border-radius: 8px; }
    .code { font-family: monospace; font-size: 12px; }
  `,
})
export class Ex21Page {
  readonly tr = inject(Translations);
  readonly languages = languages;
  readonly serverResponses = serverResponses;
  readonly count = signal(2);
  private readonly today = new Date();

  // formato en el idioma ACTUAL: se recalcula cuando este cambia
  readonly date = computed(() =>
    new Intl.DateTimeFormat(this.tr.language(), { dateStyle: 'full' }).format(this.today),
  );
  readonly price = computed(() =>
    new Intl.NumberFormat(this.tr.language(), { style: 'currency', currency: 'EUR' }).format(1234.5),
  );
  // el idioma de ion-datetime: un "locale" completo (idioma-país)
  readonly locale = computed(() => (this.tr.language() === 'fr' ? 'fr-FR' : 'en-US'));

  constructor() {
    addIcons({ calendarOutline });
    this.tr.start();
    // el título del documento (pestaña del navegador), traducido: un efecto,
    // que se vuelve a ejecutar cuando cambia el idioma
    const title = inject(Title);
    effect(() => title.setTitle(this.tr.t('APP.TITLE')));
  }

  // el segmento de la barra superior: su valor (de tipo SegmentValue: una
  // cadena o un número) es el idioma elegido
  chooseLanguage(value: SegmentValue | undefined): void {
    this.tr.changeLanguage(String(value));
  }
}
<!-- ======================================================================
     ex21.page.html - una página en dos idiomas
     ====================================================================== -->

<ion-header>
  <ion-toolbar color="primary">
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/" />
    </ion-buttons>
    <ion-title>{{ tr.t('APP.TITLE') }}</ion-title>
    <!-- los idiomas: un "segmento", botones de los que solo uno está elegido -->
    <ion-segment slot="end" [value]="tr.language()" (ionChange)="chooseLanguage($event.detail.value)">
      @for (l of languages; track l) {
        <ion-segment-button [value]="l"><ion-label>{{ l.toUpperCase() }}</ion-label></ion-segment-button>
      }
    </ion-segment>
  </ion-toolbar>
</ion-header>

<ion-content class="ion-padding">
  <ion-card>
    <ion-card-content>
      <div>{{ tr.t('HOME.HELLO', { name: 'Marie' }) }}</div>
      <div>{{ tr.t('HOME.TODAY', { date: date() }) }}</div>
      <div>{{ tr.t('HOME.PRICE', { price: price() }) }}</div>
      <!-- count: elige la forma del plural y reemplaza {{count}} -->
      <p><strong>{{ tr.t('HOME.APPOINTMENTS', { count: count() }) }}</strong></p>
      <ion-button fill="clear" size="small" (click)="count.set(count() + 1)">
        {{ tr.t('HOME.ADD') }}</ion-button>
      <ion-button fill="clear" size="small" [disabled]="count() === 0" (click)="count.set(count() - 1)">
        {{ tr.t('HOME.REMOVE') }}</ion-button>
      <br />
      <!-- el botón id="calendar" abre el diálogo modal trigger="calendar" -->
      <ion-button id="calendar" fill="outline">
        <ion-icon slot="start" name="calendar-outline" />
        {{ tr.t('HOME.CALENDAR') }}
      </ion-button>
      <ion-modal class="calendar" trigger="calendar">
        <!-- ng-template: el contenido solo se crea cuando se abre el diálogo -->
        <ng-template>
          <!-- locale: los meses y los días en el idioma actual (Intl);
               firstDayOfWeek: lunes (1) en francés, domingo (0) en inglés -->
          <ion-datetime presentation="date" min="2026-01-01" max="2027-12-31"
            [locale]="locale()" [firstDayOfWeek]="tr.language() === 'fr' ? 1 : 0" [showDefaultButtons]="true"
            [doneText]="tr.t('HOME.CALENDAR_OK')" [cancelText]="tr.t('HOME.CALENDAR_CANCEL')" />
        </ng-template>
      </ion-modal>
    </ion-card-content>
  </ion-card>

  <ion-card>
    <ion-card-header>
      <ion-card-subtitle>{{ tr.t('SERVER.TITLE') }}</ion-card-subtitle>
    </ion-card-header>
    <ion-card-content>
      <p>{{ tr.t('SERVER.EXPLANATION') }}</p>
      <!-- la clave del servidor ES una clave del diccionario; params proporciona sus parámetros -->
      @for (r of serverResponses; track r.key) {
        <p class="code ion-margin-top">{{ r.statusCode }} {{ r.key }}</p>
        <p>→ {{ tr.t(r.key, r.params) }}</p>
      }
    </ion-card-content>
  </ion-card>
</ion-content>
  • líneas 25–28 (.ts): lo que el servidor devolvería para [RdvMedecins]: un código HTTP, una clave y sus parámetros;
  • línea 38 (.ts): un proveedor ESPECÍFICO de la página: [providers] en el decorador [@Component] crea una instancia de las traducciones para esta página (y sus componentes), que se destruye junto con ella. [useFactory] proporciona la función que la crea, junto con su prefijo;
  • líneas 40–42 (.ts): el tamaño de la selección de idioma y el de la ventana del calendario (un cuadro de diálogo dimensionado según su contenido, en lugar de una página completa);
  • línea 47 (.ts): las traducciones, obtenidas como un servicio;
  • líneas 54–59 (.ts): la fecha y el precio, formateados en el idioma actual por [Intl.DateTimeFormat] ([dateStyle: 'full']: “Tuesday, October 6, 2026”, “mardi 6 octobre 2026”) e [Intl.NumberFormat] ([style: 'currency']: “€1,234.50”, “1 234,50 €”). Son signals calculadas: detectan el idioma y se recalculan cuando este cambia. (Los pipes [date] y [currency] de [Angular] también aceptan un idioma como parámetro, pero en ese caso hay que registrar las reglas de cada idioma, como lo hace [main.ts] para el francés.)
  • línea 61 (.ts): el idioma del calendario, en el formato idioma-país que espera [<ion-datetime>];
  • línea 65 (.ts): el idioma de origen;
  • líneas 68–69 (.ts): el título del documento (la pestaña del navegador), traducido: el servicio [Title] de [Angular], invocado por un efecto, que se vuelve a ejecutar cuando cambia el idioma;
  • líneas 74–76 (.ts): selección del idioma;
  • línea 10 (html): el título de la página, traducido;
  • líneas 12–16 (html): la selección de idioma en la barra superior: un [<ion-segment>], formado por botones, de los cuales solo uno está seleccionado ([value]), el equivalente del [SegmentedButton] de [Flutter];
  • líneas 23–25 (HTML): texto con parámetros. La fecha y el precio, ya formateados, se pasan como parámetros;
  • línea 27 (html): [count] selecciona la forma plural y reemplaza [{{count}}];
  • líneas 34–47 (html): el calendario, en una ventana modal ([<ion-modal>]) que abre el botón cuyo [id] se especifica en su atributo [trigger]. Su contenido, en un [<ng-template>], se crea solo cuando se abre la ventana. [<ion-datetime>] formatea los meses y días mediante [Intl], en el idioma especificado por su atributo [[locale]]; [[firstDayOfWeek]]: la semana comienza el lunes en francés y el domingo en inglés. Sus botones (“Done”, “Cancel” de forma predeterminada) no son traducidos por [locale]: [[doneText]] y [[cancelText]] reciben los textos de nuestros diccionarios. Esto era el paquete [flutter_localizations] junto con [Flutter];
  • líneas 58–61 (html): lo que devolvería el servidor [RdvMedecins]. La clave del servidor ES una clave del diccionario; sus parámetros son los del texto.

7.1.4. El resultado

En inglés (izquierda); en francés, después de una adición (centro); el calendario, en francés (derecha):

Cambiar el idioma vuelve a traducir toda la pantalla sin reiniciar ni hacer ninguna solicitud al servidor: el idioma y el diccionario son signals, y todo lo que las lee (texto de la plantilla, fecha, precio, título) las sigue. El idioma seleccionado se almacena en el dispositivo: vuelva a iniciar la aplicación (en el navegador, recargue la página) y se abrirá en el último idioma seleccionado.