Skip to content

7. Internacionalização

7.1. Exemplo 21: Uma aplicação bilíngue

Uma aplicação bilíngue tem três tipos de texto a traduzir:

  • os textos da aplicação: rótulos e mensagens. Eles são armazenados em dicionários, um por idioma;
  • datas e valores: o objeto [Intl] do [JavaScript] os formata no idioma desejado (veja o Exemplo 09);
  • os textos do próprio [Ionic] : os meses e dias do calendário, seus botões. O calendário ([<ion-datetime>]) recebe o idioma por meio do atributo [locale].

7.1.1. Os dicionários

{
  "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 tem uma chave ("HOME.HELLO"). Os parâmetros são escritos como [{{name}}]; um texto no plural tem várias chaves: [_zero], [_one], [_other]. Essas são as convenções da biblioteca [JavaScript] [i18next] , usada pelos clientes [React] e [Vue.js] do [RdvMedecins]: o estudo de caso usará os dicionários deles, complementados com algumas chaves adicionais. O dicionário em inglês tem as mesmas chaves:

{
  "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:"
  }
}

Os arquivos da pasta [public/] do projeto são entregues como estão com a aplicação (em um navegador: no endereço /i18n/ex21-fr.json; no [Android]: dentro da própria aplicação). Em comparação com os dicionários do exemplo do [Flutter], duas chaves foram adicionadas: [CALENDAR_OK] e [CALENDAR_CANCEL], que correspondem aos botões do calendário (discutidos adiante).

7.1.2. Traduções

// =========================================================================
// src/app/ex21-i18n/translations.ts - dicionários, um idioma atual
// -------------------------------------------------------------------------
// Cada idioma tem seu DICIONÁRIO, um arquivo JSON distribuído com
// a aplicação (public/i18n/ex21-fr.json, ex21-en.json), em que cada texto
// tem uma CHAVE ("HOME.HELLO"):
//   - t('HOME.HELLO', { name: 'Marie' }): o texto do idioma
//     ATUAL, cujos parâmetros {{name}} são substituídos;
//   - t('HOME.APPOINTMENTS', { count: n }): um texto no plural;
//     escolhemos a chave APPOINTMENTS_zero, _one ou _other conforme n e as regras
//     do idioma (em francês, 0 e 1 são singular; em inglês,
//     apenas 1);
//   - changeLanguage('fr'): carrega o outro dicionário. O idioma e o
//     dicionário são SIGNALS: os templates que chamam t() são
//     atualizados, eles se traduzem novamente.
// Essas são as convenções da biblioteca JavaScript i18next: os
// dicionários são os dos clientes Vue.js, Angular e React do
// RdvMedecins... e o servidor, que só retorna CHAVES
// ("ERRORS.LOGIN_TAKEN"), também os usa.
// =========================================================================

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

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

// um dicionário: textos, ou outros dicionários (JSON aninhado)
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: o início do nome dos dicionários (public/i18n/<prefix>-<language>.json)
  constructor(private readonly prefix: string) {}

  // o idioma inicial: o armazenado no dispositivo, senão o do
  // celular (se for conhecido), senão o 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: lê um arquivo distribuído com a aplicação (pasta public/)
    const response = await fetch(`i18n/${this.prefix}-${language}.json`);
    this._dictionary.set((await response.json()) as Dictionary);
    this._language.set(language);
    // o idioma da página (leitores de tela, hifenização de palavras...)
    document.documentElement.lang = language;
    await DeviceStorage.set({ key: `${this.prefix}.language`, value: language });
  }

  // "HOME.HELLO" -> dictionary['HOME']['HELLO']; undefined se ausente
  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: a forma do plural ("one", "other"...), conforme as
      // regras do idioma; a chave _zero, se existir, vence 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);
    // uma chave desconhecida é exibida como está: vemos imediatamente o que está faltando
    if (text === undefined) return key;
    // {{name}} -> o valor do parâmetro name
    return text.replace(/\{\{(\w+)\}\}/g, (all, name: string) => String(params[name] ?? all));
  }
}
  • linha 25: os idiomas da aplicação;
  • linha 28: o tipo de um dicionário—um objeto em que cada propriedade é um texto ou outro dicionário (o tipo é recursivo: ele faz referência a si mesmo);
  • linhas 30–33: a classe de traduções armazena o idioma atual e seu dicionário em variáveis. Uma classe simples, não um serviço [@Injectable]: cada usuário a cria com seu próprio prefixo (linha 36; o Exemplo 25 terá seus dicionários, [ex25-fr.json]...). Ela será fornecida à página por uma “factory” (discutida adiante);
  • linha 36: [private readonly prefix] nos parâmetros do construtor declara E inicializa um campo: um atalho do [TypeScript];
  • linhas 40–44: o idioma de origem: o armazenado no dispositivo (o plugin [@capacitor/preferences] do Exemplo 20); caso contrário, o idioma do celular ([navigator.language]: “en-US”, do qual são mantidas as duas primeiras letras), se conhecido; caso contrário, o inglês;
  • linhas 46–54: mudar de idioma: ler o dicionário com [fetch], a função do [JavaScript] que lê um endereço (neste caso, um arquivo incluído na aplicação) e retorna uma [Promise] que representa a resposta; decodificar seu conteúdo JSON ([response.json()], outra [Promise]); armazenar o dicionário e o idioma em seus respectivos campos; atualizar o idioma da página (o atributo [lang] da tag [<html>], útil para leitores de tela); salvar a seleção no dispositivo. Poderíamos ter usado o cliente HTTP do [Angular] (Exemplo 22): [fetch] evita depender dele em uma classe simples;
  • linhas 57–63: busca de uma chave “HOME.HELLO” no dicionário: descemos parte por parte ([split('.')]) pelos objetos JSON aninhados. [typeof node === 'object'] é uma verificação de tipo que “restringe” o tipo da variável no ramo em que é verdadeira: o [TypeScript] passa então a saber que [node] é um dicionário. A leitura do signal ([this._dictionary()], linha 58) é essencial: um template que chama [t()] lê o signal dessa forma e será atualizado quando o dicionário mudar;
  • Linhas 65–79: a tradução. Para um plural (um parâmetro numérico [count]), [Intl.PluralRules] retorna a forma plural de acordo com as regras do idioma: [select(n)] resulta em [one] ou [other] (outros idiomas também têm [two], [few], [many]). Em francês, 0 e 1 são singulares ([one]); em inglês, apenas 1. A chave [_zero], se existir, tem precedência sobre 0 (linha 72), assim como no [i18next]. Uma chave desconhecida é exibida como está (linha 76): você vê imediatamente o que está faltando. Por fim (linha 78), cada [{{name}}] é substituído pelo valor do parâmetro: uma expressão regular, [/\{\{(\w+)\}\}/g], e uma função que recebe cada correspondência ([all]) e o nome capturado entre parênteses ([name]).

Por que não usar a ferramenta oficial do [Angular]? [Angular] tem seu próprio sistema de internacionalização ([@angular/localize]): marcamos os textos dos templates ([<p i18n>Hello</p>]), extraímos as traduções para arquivos, e a compilação produz UMA aplicação para cada idioma. Essa é a melhor solução para um site em que todos os textos são conhecidos de antemão. No entanto, ela não troca de idioma “em tempo real”, e nosso servidor retorna chaves (“ERRORS.LOGIN_TAKEN”) que precisam ser traduzidas em tempo de execução: um dicionário, consultado pela chave, é muito mais adequado para isso e nos permite compartilhar dicionários com outros clientes. Existem também bibliotecas que fazem isso para o [Angular] ([ngx-translate], [Transloco]): nosso serviço é uma versão mínima delas.

7.1.3. A página traduzida

// =========================================================================
// src/app/ex21-i18n/ex21.page.ts - uma aplicação em dois idiomas
// -------------------------------------------------------------------------
//   - os TEXTOS da aplicação: os dicionários (translations.ts),
//     fornecidos à página por injeção de dependência (providers);
//   - as datas e os valores: o objeto Intl do JavaScript, no
//     idioma atual (veja o exemplo 09);
//   - os textos do PRÓPRIO Ionic (o calendário): o atributo locale
//     de <ion-datetime>, e seus botões, traduzidos pelos nossos dicionários.
// Mudar o idioma traduz a tela inteira novamente, sem 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';

// o que o servidor RdvMedecins retornaria (veja o capítulo sobre a caixa-preta)
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',
  // um provider ESPECÍFICO da página: as traduções dos dicionários 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();

  // formatação no idioma ATUAL: recalculada quando ele muda
  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),
  );
  // o idioma de ion-datetime: um "locale" completo (idioma-país)
  readonly locale = computed(() => (this.tr.language() === 'fr' ? 'fr-FR' : 'en-US'));

  constructor() {
    addIcons({ calendarOutline });
    this.tr.start();
    // o título do documento (aba do navegador), traduzido: um effect,
    // reexecutado quando o idioma muda
    const title = inject(Title);
    effect(() => title.setTitle(this.tr.t('APP.TITLE')));
  }

  // o segment da barra superior: seu valor (do tipo SegmentValue: uma
  // string ou um número) é o idioma escolhido
  chooseLanguage(value: SegmentValue | undefined): void {
    this.tr.changeLanguage(String(value));
  }
}
<!-- ======================================================================
     ex21.page.html - uma página em dois 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>
    <!-- os idiomas: um "segment", botões dos quais apenas um é escolhido -->
    <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: escolhe a forma do plural e substitui {{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 />
      <!-- o botão id="calendar" abre o 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: o conteúdo só é criado quando o diálogo abre -->
        <ng-template>
          <!-- locale: os meses e os dias no idioma atual (Intl);
               firstDayOfWeek: segunda-feira (1) em francês, domingo (0) em 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>
      <!-- a chave do servidor É uma chave do dicionário; params fornece seus 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>
  • linhas 25–28 (.ts): o que o servidor retornaria para o [RdvMedecins]: um código HTTP, uma chave e seus parâmetros;
  • linha 38 (.ts): um provider ESPECÍFICO da página: [providers] no decorador [@Component] cria uma instância das traduções para esta página (e seus componentes), que é destruída junto com ela. [useFactory] fornece a função que a cria, junto com seu prefixo;
  • linhas 40–42 (.ts): o tamanho da seleção de idioma e o da janela do calendário (uma caixa de diálogo dimensionada de acordo com seu conteúdo, em vez de uma página inteira);
  • linha 47 (.ts): as traduções, obtidas como um serviço;
  • linhas 54–59 (.ts): a data e o preço, formatados no idioma atual por [Intl.DateTimeFormat] ([dateStyle: 'full']: “Tuesday, October 6, 2026”, “mardi 6 octobre 2026”) e [Intl.NumberFormat] ([style: 'currency']: “€1,234.50”, “1 234,50 €”). Eles são signals calculados: detectam o idioma e são recalculados quando ele muda. (Os pipes [date] e [currency] do [Angular] também aceitam um idioma como parâmetro, mas nesse caso é preciso registrar as regras de cada idioma, como o [main.ts] faz para o francês.)
  • linha 61 (.ts): o idioma do calendário, no formato idioma-país esperado por [<ion-datetime>];
  • linha 65 (.ts): o idioma de origem;
  • linhas 68–69 (.ts): o título do documento (a aba do navegador), traduzido: o serviço [Title] do [Angular], chamado por um efeito, que é reexecutado quando o idioma muda;
  • linhas 74–76 (.ts): seleção de idioma;
  • linha 10 (html): o título da página, traduzido;
  • linhas 12–16 (html): a seleção de idioma na barra superior: um [<ion-segment>], composto de botões, dos quais apenas um é selecionado ([value]), o equivalente ao [SegmentedButton] do [Flutter];
  • linhas 23–25 (HTML): texto parametrizado. A data e o preço, já formatados, são passados como parâmetros;
  • linha 27 (html): [count] seleciona a forma plural e substitui [{{count}}];
  • Linhas 34–47 (html): o calendário, em uma janela modal ([<ion-modal>]) aberta pelo botão cujo [id] é especificado pelo seu atributo [trigger]. Seu conteúdo, em um [<ng-template>], é criado somente quando a janela é aberta. [<ion-datetime>] formata os meses e dias usando [Intl], no idioma especificado pelo seu atributo [[locale]]; [[firstDayOfWeek]]: a semana começa na segunda-feira em francês e no domingo em inglês. Seus botões (“Done”, “Cancel” por padrão) não são traduzidos por [locale]: [[doneText]] e [[cancelText]] recebem os textos dos nossos dicionários. Isso era feito pelo pacote [flutter_localizations] junto com o [Flutter];
  • linhas 58–61 (html): o que o servidor [RdvMedecins] retornaria. A chave do servidor É uma chave do dicionário; seus parâmetros são os do texto.

7.1.4. A saída

Em inglês (à esquerda); em francês, após uma adição (no meio); o calendário, em francês (à direita):

Mudar o idioma retraduz a tela inteira sem reiniciar nem fazer requisições ao servidor: o idioma e o dicionário são signals, e tudo que os lê (texto do template, data, preço, título) os acompanha. O idioma selecionado é armazenado no dispositivo: reinicie o aplicativo (no navegador, recarregue a página), e ele será aberto no último idioma selecionado.