Explicação sobre i18n no Angular: em tempo de compilação vs. em tempo de execução

A internacionalização no Angular pode seguir dois modelos diferentes: em tempo de compilação ou em tempo de execução. A abordagem oficial utiliza @angular/localize, o que gera uma compilação separada para cada idioma. Essa configuração é estável e rápida em tempo de execução, mas exige planejamento para várias implantações e não permite a troca de idioma dentro do aplicativo.

Para implementá-lo, você marca o texto nos modelos e no TypeScript, extrai as traduções para arquivos e, em seguida, compila uma versão do aplicativo para cada localidade. Cada idioma é disponibilizado em sua própria URL; assim, os usuários alternam entre os idiomas por meio da navegação, em vez de usar um botão de alternância dentro do aplicativo.

Se você precisar de uma alternância dinâmica sem recarregamentos, as bibliotecas de tempo de execução cuidam disso. Entre as opções mais populares estão o ngx-translate e o angular-i18next. Elas carregam as traduções sob demanda e atualizam a interface do usuário instantaneamente, com diferentes vantagens e desvantagens em relação à configuração, ao desempenho e ao suporte a SSR.

Neste artigo, explicamos como funciona o fluxo de trabalho de internacionalização (i18n) integrado ao Angular, como implementá-lo e em que casos uma biblioteca de tempo de execução é a melhor opção.

Como @angular/localize obras

A internacionalização integrada do Angular utiliza um fluxo de trabalho na fase de compilação. Você prepara as traduções antes da implantação e, em seguida, distribui uma versão compilada do aplicativo para cada idioma.

Não há troca de linguagem em tempo de execução; portanto, a configuração concentra-se na extração e na configuração da compilação.

Vamos revisar todo o fluxo de trabalho:

1. Marque o texto a ser traduzido nos modelos e no TypeScript. Use o atributo i18n para o conteúdo e os atributos HTML, e use $localize em TypeScript, de modo que as strings sejam incluídas no mesmo processo de extração.
2. Extraia as mensagens para um arquivo de tradução usando o Angular CLI. Isso gera, por padrão, um arquivo XLIFF, com opções para outros formatos dependendo da sua configuração, contendo os IDs das mensagens e o texto de origem.
3. Traduza o arquivo extraído e mantenha os identificadores inalterados. Adicione IDs personalizados quando necessário, para que as atualizações no texto original não prejudiquem as traduções existentes nem causem incompatibilidades ocultas.
4. Crie e implante uma versão do aplicativo para cada localidade. Configure as localidades no arquivo angular.json e, em seguida, gere pacotes específicos para cada idioma, que serão servidos a partir de rotas ou domínios distintos.

A pluralização utiliza expressões do ICU. Você define casos como, por exemplo, =0, =1, ou outros, e o Angular seleciona o formulário correto com base na localidade ativa. Os idiomas diferem quanto ao número de formulários necessários; portanto, planeje a estrutura das mensagens com antecedência.

Expressões aninhadas em ICU seguem o mesmo padrão, mas aumentam a complexidade; portanto, mantenha-as legíveis e teste-as em diferentes configurações regionais.

Criação e implantação de aplicativos Angular com suporte a várias localizações

Com a internacionalização (i18n) em tempo de compilação do Angular, a implantação está diretamente ligada à forma como você configura o arquivo angular.json. Você define uma localidade de origem e um conjunto de localidades de destino, cada uma mapeada para um arquivo de tradução.

Durante a compilação, o Angular compila o aplicativo uma única vez e, em seguida, aplica substituições localizadas como uma etapa de pós-processamento. Isso significa que você não está executando compilações completas para cada idioma, mas ainda assim obtém pacotes de saída separados para cada localidade.

Cada local produz sua própria versão do aplicativo, geralmente disponibilizada em um subcaminho ou domínio. Uma configuração comum utiliza caminhos como /en/ e /fr/, sendo que cada um aponta para a saída de compilação correspondente. Essa estrutura é necessária porque o conteúdo traduzido é incorporado aos arquivos; portanto, mudar de idioma significa carregar uma compilação diferente.

A configuração do servidor passa a fazer parte da configuração de internacionalização (i18n). São necessárias regras de roteamento que direcionem as solicitações recebidas para a versão com a localidade correta.

A implementação varia muito de acordo com o ambiente — regras de reescrita diretas no Nginx versus algumas linhas declarativas no Firebase Hosting —, mas o objetivo é o mesmo. As solicitações devem ser direcionadas para o pacote localizado correto com base na estrutura da URL ou na lógica de redirecionamento.

O Angular também oferece suporte à detecção automática de idioma ao usar a renderização do lado do servidor. O servidor pode ler o Accept-Language cabeçalho e, em seguida, redirecionar os usuários para o caminho da localidade correspondente. Isso melhora a experiência na primeira visita, mas ainda assim resulta no carregamento completo da página ao alternar de idioma posteriormente.

Durante o desenvolvimento, o servidor de desenvolvimento do Angular pode atender a várias configurações regionais por meio de subcaminhos. Isso facilita os testes, mas a alternância entre idiomas ainda exige uma atualização da página, pois cada configuração regional corresponde a uma compilação separada.

Esse modelo traz implicações claras para a infraestrutura. Você gerencia vários artefatos de compilação, configura o roteamento para cada localidade e lida com redirecionamentos no nível do servidor. Os pipelines de CI devem levar em conta as atualizações de tradução e recompilar os resultados localizados quando o conteúdo for alterado.

Uma abordagem alternativa evita essa complexidade. Um modelo de proxy reverso, como Weglot, fica entre o servidor e o navegador. Ele traduz o conteúdo em tempo real e disponibiliza todos os idiomas a partir de uma única implantação. Isso elimina a necessidade de várias compilações e regras de roteamento. Falaremos mais sobre Weglot !

Comparando bibliotecas de tempo de execução: ngx-translate, Transloco e angular-i18next

As bibliotecas de tempo de execução resolvem um problema diferente daquele da internacionalização (i18n) integrada ao Angular. Em vez de compilar as traduções no aplicativo, elas as carregam em tempo de execução e atualizam a interface do usuário sem a necessidade de uma recarga completa.

Isso faz com que sejam mais adequadas quando os usuários precisam alternar entre idiomas dentro do aplicativo ou quando o conteúdo muda com frequência.

ngx-translate é a opção mais utilizada. Ela permite a troca instantânea de idioma por meio de trans.use(), com traduções carregadas a partir de arquivos JSON ou APIs. Funciona bem em aplicativos menores e é a única opção aqui com confirmação de Iônico compatibilidade. O SSR é possível com TransferState e carregadores personalizados, embora isso exija uma configuração. As versões mais recentes adicionaram uma API baseada em provedores, que se adapta melhor a componentes independentes.

Transloco enfoca a estrutura e a escalabilidade. Oferece suporte integrado ao SSR e uma configuração mais simples com o comando `ng add`. Também oferece suporte a traduções por escopo, o que permite o carregamento diferido de arquivos de idioma por recurso. Isso reduz o tamanho do pacote e mantém a facilidade de manutenção de aplicativos grandes. A troca de idioma utiliza setActiveLang() e atualiza a interface do usuário imediatamente.

O angular-i18next integra o ecossistema do i18next. Ele é útil se sua equipe já utiliza o i18next em outras estruturas e deseja manter a consistência entre os projetos. Ele oferece suporte aos plug-ins do núcleo do i18next, incluindo o gerenciamento do ICU. A troca de idioma geralmente exige uma atualização da página, o que limita seu uso em aplicativos que exigem atualizações instantâneas.

Aqui está uma comparação mais direta:

A escolha depende de como seu aplicativo lida com mudanças de idioma e com a escala:

• Use o ngx-translate se precisar de uma configuração simples ou de suporte ao Ionic.
• Use o Transloco para SSR ou aplicativos de grande porte com necessidades de tradução modulares.
• Use o angular-i18next se quiser garantir a compatibilidade com o i18next em várias plataformas.

💡 Se não for necessário alternar o idioma em tempo de execução e você preferir uma lógica de cliente mínima, a internacionalização (i18n) integrada ao Angular continua sendo a melhor opção.

Tradução de aplicativos Angular sem alterações no código

Existe uma terceira opção além das bibliotecas integradas de internacionalização (i18n) e de tempo de execução do Angular: ferramentas externas de tradução de sites. Essas ferramentas funcionam fora do aplicativo Angular e traduzem o resultado renderizado, em vez das strings contidas no código-fonte.

Conforme mencionado, Weglot um modelo de proxy reverso. Ele fica entre o servidor e o navegador, detecta a resposta HTML e, em seguida, apresenta versões traduzidas aos visitantes. Isso significa que você não precisa marcar strings com i18n, gerenciar arquivos de tradução em JSON nem recompilar o aplicativo para cada localidade. A configuração é mais rápida, pois a camada de tradução é gerenciada fora do Angular.

Essa abordagem também muda o local onde o trabalho de tradução é realizado. Em vez de editar arquivos no projeto, os tradutores utilizam um painel visual. Eles podem revisar páginas e aplicar regras do glossário sem precisar mexer nos modelos ou no TypeScript. Para sites de marketing com grande volume de conteúdo, isso pode reduzir o envolvimento dos desenvolvedores.

A alternância de idiomas também pode parecer mais fluida. Weglot um seletor baseado em JavaScript que atualiza o idioma exibido sem exigir um processo completo de recompilação do Angular. Isso facilita o lançamento rápido de conteúdo multilíngue.

A desvantagem é o controle. Como a tradução ocorre depois que o Angular renderiza a página, esse modelo não lida com a lógica do aplicativo que depende do idioma dentro do TypeScript. Além disso, não é a solução ideal para aplicativos Ionic e aplicativos “offline-first”, nos quais o conteúdo precisa estar dentro do próprio aplicativo, em vez de atrás de um proxy.

O SEO também depende da configuração. A tradução por proxy reverso pode permitir que as páginas traduzidas sejam indexadas, mas um simples snippet de JavaScript, snippet , não cria URLs localizadas otimizadas para SEO. Isso é importante se o tráfego de busca orgânica fizer parte da meta.

Esse modelo é ideal para equipes que desejam ter páginas multilíngues sem alterar o código do aplicativo. Ele é menos adequado quando o idioma afeta o roteamento ou a lógica de negócios. Além disso, requer uma assinatura ativa, já que o conteúdo traduzido permanece vinculado ao serviço.

Escolhendo a abordagem correta para a internacionalização (i18n) no Angular

A abordagem correta para a internacionalização no Angular depende de como seu aplicativo lida com os idiomas na prática.

A internacionalização (i18n) em tempo de compilação prioriza o desempenho e a estabilidade, enquanto as bibliotecas em tempo de execução se concentram na flexibilidade dentro da interface do usuário. Ferramentas externas eliminam a maior parte do trabalho de implementação, mas transferem o controle para fora da base de código.

Escolha @angular/localize quando o desempenho em tempo de execução é fundamental e sua equipe se sente à vontade para gerenciar compilações localizadas separadas na integração contínua (CI). Essa opção é mais adequada quando a troca de idioma pode ocorrer por meio da navegação, em vez de dentro do aplicativo.

Escolha o ngx-translate quando os usuários precisarem alternar entre idiomas sem precisar recarregar a página e você quiser uma opção de ambiente de execução amplamente adotada. É a opção mais adequada para projetos Ionic e aplicativos Angular menores.

Escolha o Transloco quando precisar de alternância em tempo de execução e de uma estrutura mais robusta para aplicativos maiores. É uma boa opção para configurações de SSR e para equipes que desejam arquivos de tradução com escopo definido e carregamento diferido.

Escolha Weglot o objetivo for um site multilíngue sem adicionar lógica de tradução à base de código do Angular. Ele é ideal para a veiculação de conteúdo e implementação rápida, mas não para aplicativos em que o comportamento do TypeScript precise mudar de acordo com o idioma.

{{banner-demonstração}}