Guides approfondis
Internationalisation

Préparer un composant pour la traduction

Pour préparer votre projet à la traduction, effectuez les actions suivantes.

  • Utilisez l'attribut i18n pour marquer du texte dans les templates des composants
  • Utilisez l'attribut i18n- pour marquer les chaînes de texte des attributs dans les templates des composants
  • Utilisez la chaîne de message balisée avec $localize pour marquer des chaînes de texte dans le code des composants

Marquer du texte dans le template d'un composant

Dans le template d'un composant, les métadonnées i18n sont la valeur de l'attribut i18n.

<element i18n="{i18n_metadata}">{string_to_translate}</element>

Utilisez l'attribut i18n pour marquer un message texte statique à traduire dans les templates de vos composants. Placez-le sur chaque balise d'élément contenant du texte fixe que vous voulez traduire.

Utile : L'attribut i18n est un attribut personnalisé que les outils et compilateurs Angular reconnaissent.

Exemple i18n

La balise <h1> suivante affiche une simple salutation en anglais, « Hello i18n ! ».

app.component.html

<h1>Hello i18n!</h1>

Pour marquer la salutation à traduire, ajoutez l'attribut i18n à la balise <h1>.

app.component.html

<h1 i18n>Hello i18n!</h1>

Utiliser une instruction conditionnelle avec i18n

La balise <div> suivante affiche du texte traduit dans le contenu du div et dans aria-label selon l'état du basculement

Traduire du texte en ligne sans élément HTML

Utilisez l'élément <ng-container> pour associer un comportement de traduction à un texte spécifique sans changer la façon dont le texte est affiché.

Utile : Chaque élément HTML crée un nouvel élément du DOM. Pour éviter de créer un nouvel élément du DOM, enveloppez le texte dans un élément <ng-container>. L'exemple suivant montre l'élément <ng-container> transformé en commentaire HTML non affiché.

<ng-container i18n>I don't output any element</ng-container>

Nommer le placeholder d'interpolation

Par défaut, Angular génère un nom de placeholder pour chaque interpolation d'un message traduit. Pour lui donner un nom explicite qui aide les traducteurs à comprendre le contexte, ajoutez un commentaire //i18n(ph="name") à l'intérieur de l'interpolation.

<element i18n>{{ expression //i18n(ph="placeholder_name") }}</element>

Par exemple :

<p i18n>Hello, {{ username //i18n(ph="name") }}!</p>

C'est l'équivalent, dans le template, du nommage d'un placeholder dans le code d'un composant avec $localize :

$localize`Hello, ${username}:name:!`;

Marquer les attributs des éléments pour la traduction

Dans le template d'un composant, les métadonnées i18n sont la valeur de l'attribut i18n-{attribute_name}.

<element i18n-{attribute_name}="{i18n_metadata}" {attribute_name}="{attribute_value}" />

Les attributs des éléments HTML contiennent du texte qui doit être traduit avec le reste du texte affiché dans le template du composant.

Utilisez i18n-{attribute_name} avec n'importe quel attribut de n'importe quel élément et remplacez {attribute_name} par le nom de l'attribut. Utilisez la syntaxe suivante pour attribuer une signification, une description et un identifiant personnalisé.

i18n-{attribute_name}="{meaning}|{description}@@{id}"

Exemple i18n-title

Pour traduire le titre d'une image, examinez cet exemple. L'exemple suivant affiche une image avec un attribut title.

app.component.html

<img [src]="logo" title="Angular logo" alt="Angular logo" />

Pour marquer l'attribut title à traduire, effectuez l'action suivante.

Ajoutez l'attribut i18n-title

L'exemple suivant montre comment marquer l'attribut title de la balise img en ajoutant i18n-title.

app.component.html

<img [src]="logo" i18n-title title="Angular logo" alt="Angular logo" />

Marquer du texte dans le code d'un composant

Dans le code d'un composant, le texte source à traduire et les métadonnées sont entourés de caractères backtick (`).

Utilisez la chaîne de message balisée avec $localize pour marquer une chaîne à traduire dans votre code.

$localize`string_to_translate`;

Les métadonnées i18n sont entourées de caractères deux-points (:) et précèdent le texte source à traduire.

$localize`:{i18n_metadata}:string_to_translate`;

Inclure du texte interpolé

Incluez des interpolations dans une chaîne de message balisée avec $localize.

$localize`string_to_translate ${variable_name}`;

Nommer le placeholder d'interpolation 

$localize`string_to_translate ${variable_name}:placeholder_name:`;

Syntaxe conditionnelle pour les traductions 

return this.show ? $localize`Show Tabs` : $localize`Hide tabs`;

Métadonnées i18n pour la traduction 

{meaning}|{description}@@{custom_id}

Les paramètres suivants fournissent du contexte et des informations supplémentaires pour éviter toute confusion au traducteur.

Paramètre de métadonnées Détails
Identifiant personnalisé Fournit un identifiant personnalisé
Description Fournit des informations ou un contexte supplémentaires
Signification Fournit la signification ou l'intention du texte dans le contexte spécifique

Pour en savoir plus sur les identifiants personnalisés, consultez Gérer le texte marqué avec des identifiants personnalisés.

Ajouter des descriptions et des significations utiles

Pour traduire un message texte avec précision, fournissez des informations ou un contexte supplémentaires au traducteur.

Ajoutez une description du message texte comme valeur de l'attribut i18n ou de la chaîne de message balisée avec $localize.

L'exemple suivant montre la valeur de l'attribut i18n.

app.component.html

<h1 i18n="An introduction header for this sample">Hello i18n!</h1>

L'exemple suivant montre la valeur de la chaîne de message balisée avec $localize avec une description.

$localize`:An introduction header for this sample:Hello i18n!`;

Le traducteur peut aussi avoir besoin de connaître la signification ou l'intention du message texte dans le contexte particulier de cette application, afin de le traduire de la même façon que d'autres textes ayant la même signification. Commencez la valeur de l'attribut i18n par la signification et séparez-la de la description avec le caractère | : {meaning}|{description}.

Exemple h1

Par exemple, vous pouvez vouloir préciser que la balise <h1> est un en-tête de site qui doit être traduit de la même façon, qu'il soit utilisé comme en-tête ou référencé dans une autre section du texte.

L'exemple suivant montre comment préciser que la balise <h1> doit être traduite comme un en-tête ou référencée ailleurs.

app.component.html

<h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1>

Résultat : tout texte marqué avec site header comme signification est traduit exactement de la même façon.

L'exemple de code suivant montre la valeur de la chaîne de message balisée avec $localize avec une signification et une description.

$localize`:site header|An introduction header for this sample:Hello i18n!`;

Comment les significations contrôlent l'extraction et la fusion du texte

L'outil d'extraction d'Angular génère une entrée d'unité de traduction pour chaque attribut i18n d'un template. L'outil d'extraction d'Angular attribue à chaque unité de traduction un identifiant unique fondé sur son texte source et sa signification. La description n'affecte pas l'identifiant.

Utile : Pour en savoir plus sur l'outil d'extraction d'Angular, consultez Travailler avec les fichiers de traduction.

Des éléments de texte identiques avec des significations différentes sont extraits avec des identifiants différents. Par exemple, si le mot « right » est utilisé avec les deux définitions suivantes à deux endroits différents, le mot est traduit différemment et réintégré dans l'application sous forme d'entrées de traduction distinctes.

  • correct comme dans « you are right »
  • direction comme dans « turn right »

Si des éléments de texte identiques remplissent les conditions suivantes, ils ne sont extraits qu'une seule fois et utilisent le même identifiant.

  • Même signification ou définition
  • Descriptions différentes

Cette unique entrée de traduction est réintégrée dans l'application partout où ces éléments de texte identiques apparaissent.

Expressions ICU

Les expressions ICU vous aident à marquer du texte alternatif dans les templates des composants selon des conditions. Une expression ICU comprend une propriété de composant, une clause ICU et les instructions case, entourées d'une accolade ouvrante ({) et d'une accolade fermante (}).

{ component_property, icu_clause, case_statements }

La propriété du composant définit la variable. Une clause ICU définit le type de texte conditionnel.

Clause ICU Détails
plural Marque l'utilisation de nombres au pluriel
select Marque des choix de texte alternatif selon les valeurs de chaîne que vous définissez

Pour simplifier la traduction, utilisez les clauses International Components for Unicode (clauses ICU) avec des expressions régulières.

Utile : Les clauses ICU respectent le format de message ICU spécifié dans les règles de pluralisation du CLDR.

Marquer les pluriels

Les langues ont des règles de pluralisation différentes, ce qui rend la traduction plus difficile. Comme les autres locales expriment la cardinalité différemment, vous devrez peut-être définir des catégories de pluralisation qui ne correspondent pas à celles de l'anglais. Utilisez la clause plural pour marquer les expressions qui risquent de ne pas avoir de sens si elles sont traduites mot à mot.

{ component_property, plural, pluralization_categories }

Après la catégorie de pluralisation, saisissez le texte par défaut (en anglais) entouré d'une accolade ouvrante ({) et d'une accolade fermante (}).

pluralization_category { }

Les catégories de pluralisation suivantes sont disponibles pour l'anglais et peuvent changer selon la locale.

Catégorie de pluralisation Détails Exemple
zero La quantité est zéro =0 { }
zero { }
one La quantité est 1 =1 { }
one { }
two La quantité est 2 =2 { }
two { }
few La quantité est 2 ou plus few { }
many La quantité est un grand nombre many { }
other La quantité par défaut other { }

Si aucune des catégories de pluralisation ne correspond, Angular utilise other, qui correspond au repli standard pour une catégorie manquante.

other { default_quantity }

Utile : Pour en savoir plus sur les catégories de pluralisation, consultez Choosing plural category names dans le CLDR - Unicode Common Locale Data Repository.

Contexte : certaines locales ne prennent pas en charge certaines catégories de pluralisation

De nombreuses locales ne prennent pas en charge certaines catégories de pluralisation. La locale par défaut (en-US) utilise une fonction plural() très simple qui ne prend pas en charge la catégorie de pluralisation few. Une autre locale avec une fonction plural() simple est es. L'exemple de code suivant montre la fonction plural() de en-US.

function plural(n: number): number {
  let i = Math.floor(Math.abs(n)),
    v = n.toString().replace(/^[^.]*\.?/, '').length;
  if (i === 1 && v === 0) return 1;
  return 5;
}

La fonction plural() ne renvoie que 1 (one) ou 5 (other). La catégorie few ne correspond jamais.

Exemple minutes

Supposons que vous vouliez afficher la phrase suivante en anglais, où x est un nombre.

updated x minutes ago

Et que vous vouliez aussi afficher les phrases suivantes selon la cardinalité de x.

updated just now
updated one minute ago

Utilisez du balisage HTML et des interpolations. L'exemple de code suivant montre comment utiliser la clause plural pour exprimer les trois situations précédentes dans un élément <span>.

app.component.html

<span i18n
  >Updated
  {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span
>

Examinez les détails suivants de l'exemple de code précédent.

Paramètres Détails
minutes Le premier paramètre indique que la propriété du composant est minutes et détermine le nombre de minutes.
plural Le deuxième paramètre indique que la clause ICU est plural.
=0 {just now} Pour zéro minute, la catégorie de pluralisation est =0. La valeur est just now.
=1 {one minute} Pour une minute, la catégorie de pluralisation est =1. La valeur est one minute.
other {{{minutes}} minutes ago} Pour toute cardinalité sans correspondance, la catégorie de pluralisation par défaut est other. La valeur est {{minutes}} minutes ago.

{{minutes}} est une interpolation.

Marquer les alternatives et les expressions imbriquées

La clause select marque des choix de texte alternatif selon les valeurs de chaîne que vous définissez.

{ component_property, select, selection_categories }

Traduisez toutes les alternatives pour afficher un texte alternatif selon la valeur d'une variable.

Après la catégorie de sélection, saisissez le texte (en anglais) entouré d'une accolade ouvrante ({) et d'une accolade fermante (}).

selection_category { text }

Les locales ont des constructions grammaticales différentes, ce qui rend la traduction plus difficile. Utilisez du balisage HTML. Si aucune des catégories de sélection ne correspond, Angular utilise other, qui correspond au repli standard pour une catégorie manquante.

other { default_value }

Exemple gender

Supposons que vous vouliez afficher la phrase suivante en anglais.

The author is other

Et que vous vouliez aussi afficher les phrases suivantes selon la propriété gender du composant.

The author is female
The author is male

L'exemple de code suivant montre comment lier la propriété gender du composant et utiliser la clause select pour exprimer les trois situations précédentes dans un élément <span>.

La propriété gender associe les sorties à chacune des valeurs de chaîne suivantes.

Valeur Valeur en anglais
female female
male male
other other

La clause select associe les valeurs aux traductions appropriées. L'exemple de code suivant montre la propriété gender utilisée avec la clause select.

app.component.html

<span i18n>The author is {gender, select, male {male} female {female} other {other}}</span>

Exemple gender et minutes

Combinez différentes clauses, comme les clauses plural et select. L'exemple de code suivant montre des clauses imbriquées fondées sur les exemples gender et minutes.

app.component.html

<span i18n
  >Updated:
  {minutes, plural,
    =0 {just now}
    =1 {one minute ago}
    other {{{ minutes }} minutes ago by {gender, select, male {male} female {female} other {other}}}
  }
</span>

Et ensuite ?