Para preparar seu projeto para tradução, complete as seguintes ações.
- Use o atributo
i18npara marcar texto em templates de components - Use o atributo
i18n-para marcar strings de texto de atributos em templates de components - Use a tagged message string
$localizepara marcar strings de texto no código do component
Marcar texto no template do component
Em um template de component, os metadados i18n são o valor do atributo i18n.
<element i18n="{i18n_metadata}">{string_to_translate}</element>Use o atributo i18n para marcar uma mensagem de texto estática em seus templates de components para tradução.
Coloque-o em cada tag de elemento que contenha texto fixo que você deseja traduzir.
HELPFUL: O atributo i18n é um atributo personalizado que as ferramentas e compiladores do Angular reconhecem.
Exemplo de i18n
A seguinte tag <h1> exibe uma saudação simples em inglês, "Hello i18n!".
src/app/app.component.html
<h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>Para marcar a saudação para tradução, adicione o atributo i18n à tag <h1>.
src/app/app.component.html
<h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>
Usando declaração condicional com i18n
A seguinte tag <div> exibirá texto traduzido como parte da div e aria-label baseado no status de alternância
src/app/app.component.html
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader"> Hello i18n!</h1><ng-container i18n>I don't output any element</ng-container><br /><img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/><br><button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button><span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>({{ minutes }})<br><br><button type="button" (click)="male()">♂</button><button type="button" (click)="female()">♀</button><button type="button" (click)="other()">⚧</button><span i18n>The author is {gender, select, male {male} female {female} other {other}}</span><br><br><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><br><br><button type="button" (click)="toggleDisplay()">Toggle</button><div i18n [attr.aria-label]="toggleAriaLabel()">{{toggle()}}</div>src/app/app.component.ts
import {Component, computed, signal} from '@angular/core';import {$localize} from '@angular/localize/init';@Component({ selector: 'app-root', templateUrl: './app.component.html',})export class AppComponent { minutes = 0; gender = 'female'; fly = true; logo = '${this.baseUrl}/angular.svg'; readonly toggle = signal(false); readonly toggleAriaLabel = computed(() => { return this.toggle() ? $localize`:Toggle Button|A button to toggle status:Show` : $localize`:Toggle Button|A button to toggle status:Hide`; }); inc(i: number) { this.minutes = Math.min(5, Math.max(0, this.minutes + i)); } male() { this.gender = 'male'; } female() { this.gender = 'female'; } other() { this.gender = 'other'; } toggleDisplay() { this.toggle.update((toggle) => !toggle); }}Traduzir texto inline sem elemento HTML
Use o elemento <ng-container> para associar um comportamento de tradução para texto específico sem alterar a forma como o texto é exibido.
HELPFUL: Cada elemento HTML cria um novo elemento DOM.
Para evitar criar um novo elemento DOM, envolva o texto em um elemento <ng-container>.
O exemplo a seguir mostra o elemento <ng-container> transformado em um comentário HTML não exibido.
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader"> Hello i18n!</h1><ng-container i18n>I don't output any element</ng-container><br /><img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/><br><button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button><span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>({{ minutes }})<br><br><button type="button" (click)="male()">♂</button><button type="button" (click)="female()">♀</button><button type="button" (click)="other()">⚧</button><span i18n>The author is {gender, select, male {male} female {female} other {other}}</span><br><br><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><br><br><button type="button" (click)="toggleDisplay()">Toggle</button><div i18n [attr.aria-label]="toggleAriaLabel()">{{toggle()}}</div>Marcar atributos de elementos para traduções
Em um template de component, os metadados i18n são o valor do atributo i18n-{attribute_name}.
<element i18n-{attribute_name}="{i18n_metadata}" {attribute_name}="{attribute_value}" />Os atributos de elementos HTML incluem texto que deve ser traduzido junto com o resto do texto exibido no template do component.
Use i18n-{attribute_name} com qualquer atributo de qualquer elemento e substitua {attribute_name} pelo nome do atributo.
Use a seguinte sintaxe para atribuir um significado, descrição e ID personalizado.
i18n-{attribute_name}="{meaning}|{description}@@{id}"
Exemplo de i18n-title
Para traduzir o título de uma imagem, revise este exemplo.
O exemplo a seguir exibe uma imagem com um atributo title.
src/app/app.component.html
<h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>Para marcar o atributo title para tradução, complete a seguinte ação.
Adicione o atributo
i18n-titleO exemplo a seguir mostra como marcar o atributo
titlena tagimgadicionandoi18n-title.src/app/app.component.html
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader"> Hello i18n!</h1><ng-container i18n>I don't output any element</ng-container><br /><img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/><br><button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button><span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>({{ minutes }})<br><br><button type="button" (click)="male()">♂</button><button type="button" (click)="female()">♀</button><button type="button" (click)="other()">⚧</button><span i18n>The author is {gender, select, male {male} female {female} other {other}}</span><br><br><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><br><br><button type="button" (click)="toggleDisplay()">Toggle</button><div i18n [attr.aria-label]="toggleAriaLabel()">{{toggle()}}</div>
Marcar texto no código do component
No código do component, o texto fonte de tradução e os metadados são cercados por caracteres de crase (`).
Use a tagged message string $localize para marcar uma string em seu código para tradução.
$localize`string_to_translate`;Os metadados i18n são cercados por caracteres de dois pontos (:) e precedem o texto fonte de tradução.
$localize`:{i18n_metadata}:string_to_translate`Incluir texto interpolado
Inclua interpolações em uma tagged message string $localize.
$localize`string_to_translate ${variable_name}`;Nomear o placeholder de interpolação
$localize`string_to_translate ${variable_name}:placeholder_name:`;Sintaxe condicional para traduções
return this.show ? $localize`Show Tabs` : $localize`Hide tabs`;Metadados i18n para tradução
{meaning}|{description}@@{custom_id}Os seguintes parâmetros fornecem contexto e informações adicionais para reduzir confusão para seu tradutor.
| Parâmetro de metadados | Detalhes |
|---|---|
| Custom ID | Fornecer um identificador personalizado |
| Description | Fornecer informação adicional ou contexto |
| Meaning | Fornecer o significado ou intenção do texto dentro do contexto específico |
Para informações adicionais sobre custom IDs, veja Gerenciar texto marcado com IDs personalizados.
Adicionar descrições e significados úteis
Para traduzir uma mensagem de texto com precisão, forneça informação adicional ou contexto para o tradutor.
Adicione uma descrição da mensagem de texto como o valor do atributo i18n ou tagged message string $localize.
O exemplo a seguir mostra o valor do atributo i18n.
src/app/app.component.html
<h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>O exemplo a seguir mostra o valor da tagged message string $localize com uma descrição.
$localize`:An introduction header for this sample:Hello i18n!`;O tradutor também pode precisar saber o significado ou intenção da mensagem de texto dentro deste contexto de aplicação particular, para traduzi-la da mesma forma que outro texto com o mesmo significado.
Inicie o valor do atributo i18n com o significado e separe-o da descrição com o caractere |: {meaning}|{description}.
Exemplo de h1
Por exemplo, você pode querer especificar que a tag <h1> é um cabeçalho do site que você precisa traduzido da mesma forma, seja usado como cabeçalho ou referenciado em outra seção de texto.
O exemplo a seguir mostra como especificar que a tag <h1> deve ser traduzida como um cabeçalho ou referenciada em outro lugar.
src/app/app.component.html
<h1>Hello i18n!</h1><h1 i18n>Hello i18n!</h1><h1 i18n="An introduction header for this sample">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample">Hello i18n!</h1><h1 i18n="An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="site header|An introduction header for this sample@@introductionHeader">Hello i18n!</h1><h1 i18n="@@introductionHeader">Hello i18n!</h1><img [src]="logo" title="Angular logo" alt="Angular logo"><h3 i18n="@@myId">Hello</h3><!-- ... --><p i18n="@@myId">Good bye</p>O resultado é que qualquer texto marcado com site header, como o significado, é traduzido exatamente da mesma forma.
O exemplo de código a seguir mostra o valor da tagged message string $localize com um significado e uma descrição.
$localize`:site header|An introduction header for this sample:Hello i18n!`;Como os significados controlam a extração e mesclagem de texto
A ferramenta de extração do Angular gera uma entrada de unidade de tradução para cada atributo i18n em um template.
A ferramenta de extração do Angular atribui a cada unidade de tradução um ID único baseado no significado e descrição.
HELPFUL: Para mais informações sobre a ferramenta de extração do Angular, veja Trabalhar com arquivos de tradução.
Os mesmos elementos de texto com significados diferentes são extraídos com IDs diferentes. Por exemplo, se a palavra "right" usa as seguintes duas definições em dois locais diferentes, a palavra é traduzida de forma diferente e mesclada de volta na aplicação como entradas de tradução diferentes.
correctcomo em "you are right"directioncomo em "turn right"
Se os mesmos elementos de texto atenderem às seguintes condições, os elementos de texto são extraídos apenas uma vez e usam o mesmo ID.
- Mesmo significado ou definição
- Descrições diferentes
Essa única entrada de tradução é mesclada de volta na aplicação onde quer que os mesmos elementos de texto apareçam.
Expressões ICU
Expressões ICU ajudam você a marcar texto alternativo em templates de components para atender condições.
Uma expressão ICU inclui uma propriedade do component, uma cláusula ICU e as declarações case cercadas por caracteres de chave de abertura ({) e chave de fechamento (}).
{ component_property, icu_clause, case_statements }A propriedade do component define a variável. Uma cláusula ICU define o tipo de texto condicional.
| Cláusula ICU | Detalhes |
|---|---|
plural |
Marcar o uso de números no plural |
select |
Marcar escolhas para texto alternativo baseado em seus valores de string definidos |
Para simplificar a tradução, use cláusulas International Components for Unicode (cláusulas ICU) com expressões regulares.
HELPFUL: As cláusulas ICU aderem ao Formato de Mensagem ICU especificado nas regras de pluralização CLDR.
Marcar plurais
Idiomas diferentes têm regras de pluralização diferentes que aumentam a dificuldade da tradução.
Como outros locales expressam cardinalidade de forma diferente, você pode precisar definir categorias de pluralização que não se alinham com o inglês.
Use a cláusula plural para marcar expressões que podem não ser significativas se traduzidas palavra por palavra.
{ component_property, plural, pluralization_categories }Após a categoria de pluralização, insira o texto padrão (inglês) cercado por caracteres de chave de abertura ({) e chave de fechamento (}).
pluralization_category { }As seguintes categorias de pluralização estão disponíveis para o inglês e podem mudar com base no locale.
| Categoria de pluralização | Detalhes | Exemplo |
|---|---|---|
zero |
Quantidade é zero | =0 { } zero { } |
one |
Quantidade é 1 | =1 { } one { } |
two |
Quantidade é 2 | =2 { } two { } |
few |
Quantidade é 2 ou mais | few { } |
many |
Quantidade é um número grande | many { } |
other |
A quantidade padrão | other { } |
Se nenhuma das categorias de pluralização corresponder, o Angular usa other para corresponder ao fallback padrão para uma categoria ausente.
other { default_quantity }HELPFUL: Para mais informações sobre categorias de pluralização, veja Escolhendo nomes de categoria de plural no CLDR - Unicode Common Locale Data Repository.
Muitos locales não suportam algumas das categorias de pluralização.
O locale padrão (en-US) usa uma função plural() muito simples que não suporta a categoria de pluralização few.
Outro locale com uma função plural() simples é es.
O exemplo de código a seguir mostra a função plural() 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;}A função plural() retorna apenas 1 (one) ou 5 (other).
A categoria few nunca corresponde.
Exemplo de minutes
Se você deseja exibir a seguinte frase em inglês, onde x é um número.
updated x minutes agoE você também deseja exibir as seguintes frases baseado na cardinalidade de x.
updated just nowupdated one minute agoUse marcação HTML e interpolações.
O exemplo de código a seguir mostra como usar a cláusula plural para expressar as três situações anteriores em um elemento <span>.
src/app/app.component.html
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader"> Hello i18n!</h1><ng-container i18n>I don't output any element</ng-container><br /><img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/><br><button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button><span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>({{ minutes }})<br><br><button type="button" (click)="male()">♂</button><button type="button" (click)="female()">♀</button><button type="button" (click)="other()">⚧</button><span i18n>The author is {gender, select, male {male} female {female} other {other}}</span><br><br><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><br><br><button type="button" (click)="toggleDisplay()">Toggle</button><div i18n [attr.aria-label]="toggleAriaLabel()">{{toggle()}}</div>Revise os seguintes detalhes no exemplo de código anterior.
| Parâmetros | Detalhes |
|---|---|
minutes |
O primeiro parâmetro especifica que a propriedade do component é minutes e determina o número de minutos. |
plural |
O segundo parâmetro especifica que a cláusula ICU é plural. |
=0 {just now} |
Para zero minutos, a categoria de pluralização é =0. O valor é just now. |
=1 {one minute} |
Para um minuto, a categoria de pluralização é =1. O valor é one minute. |
other {{{minutes}} minutes ago} |
Para qualquer cardinalidade sem correspondência, a categoria de pluralização padrão é other. O valor é {{minutes}} minutes ago. |
{{minutes}} é uma interpolação.
Marcar alternativas e expressões aninhadas
A cláusula select marca escolhas para texto alternativo baseado em seus valores de string definidos.
{ component_property, select, selection_categories }Traduza todas as alternativas para exibir texto alternativo baseado no valor de uma variável.
Após a categoria de seleção, insira o texto (inglês) cercado por caracteres de chave de abertura ({) e chave de fechamento (}).
selection_category { text }Locales diferentes têm construções gramaticais diferentes que aumentam a dificuldade da tradução.
Use marcação HTML.
Se nenhuma das categorias de seleção corresponder, o Angular usa other para corresponder ao fallback padrão para uma categoria ausente.
other { default_value }
Exemplo de gender
Se você deseja exibir a seguinte frase em inglês.
The author is otherE você também deseja exibir as seguintes frases baseado na propriedade gender do component.
The author is femaleThe author is maleO exemplo de código a seguir mostra como vincular a propriedade gender do component e usar a cláusula select para expressar as três situações anteriores em um elemento <span>.
A propriedade gender vincula as saídas a cada um dos seguintes valores de string.
| Valor | Valor em inglês |
|---|---|
| female | female |
| male | male |
| other | other |
A cláusula select mapeia os valores para as traduções apropriadas.
O exemplo de código a seguir mostra a propriedade gender usada com a cláusula select.
src/app/app.component.html
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader"> Hello i18n!</h1><ng-container i18n>I don't output any element</ng-container><br /><img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/><br><button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button><span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>({{ minutes }})<br><br><button type="button" (click)="male()">♂</button><button type="button" (click)="female()">♀</button><button type="button" (click)="other()">⚧</button><span i18n>The author is {gender, select, male {male} female {female} other {other}}</span><br><br><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><br><br><button type="button" (click)="toggleDisplay()">Toggle</button><div i18n [attr.aria-label]="toggleAriaLabel()">{{toggle()}}</div>
Exemplo de gender e minutes
Combine cláusulas diferentes juntas, como as cláusulas plural e select.
O exemplo de código a seguir mostra cláusulas aninhadas baseadas nos exemplos gender e minutes.
src/app/app.component.html
<h1 i18n="User welcome|An introduction header for this sample@@introductionHeader"> Hello i18n!</h1><ng-container i18n>I don't output any element</ng-container><br /><img [src]="logo" i18n-title title="Angular logo" alt="Angular logo"/><br><button type="button" (click)="inc(1)">+</button> <button type="button" (click)="inc(-1)">-</button><span i18n>Updated {minutes, plural, =0 {just now} =1 {one minute ago} other {{{ minutes }} minutes ago}}</span>({{ minutes }})<br><br><button type="button" (click)="male()">♂</button><button type="button" (click)="female()">♀</button><button type="button" (click)="other()">⚧</button><span i18n>The author is {gender, select, male {male} female {female} other {other}}</span><br><br><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><br><br><button type="button" (click)="toggleDisplay()">Toggle</button><div i18n [attr.aria-label]="toggleAriaLabel()">{{toggle()}}</div>