Traduza sua aplicação Analog (Angular) usando Intlayer | Internacionalização (i18n)

Sumário

O que é Intlayer?

Intlayer é uma biblioteca de internacionalização (i18n) inovadora e de código aberto, projetada para simplificar o suporte multilíngue em aplicações web modernas.

Com o Intlayer, você pode:

• Gerenciar traduções facilmente usando dicionários declarativos ao nível do componente.
• Localizar metadados, rotas e conteúdo dinamicamente.
• Garantir suporte ao TypeScript com tipos autogerados, melhorando o autocompletar e a detecção de erros.
• Beneficiar-se de recursos avançados, como detecção e troca dinâmica de idioma (locale).

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Analog

Veja o Modelo de Aplicação no GitHub.

Passo 1: Instalar Dependências

Instale os pacotes necessários usando npm:

npm install intlayer angular-intlayer vite-intlayernpx intlayer init

• intlayer

  O pacote principal que fornece ferramentas de internacionalização para gerenciamento de configuração, tradução, declaração de conteúdo, transpilação e comandos CLI.

• angular-intlayer O pacote que integra o Intlayer com aplicações Angular. Ele fornece provedores de contexto e hooks para internacionalização Angular.

• vite-intlayer O pacote que integra o Intlayer com o Vite. Ele fornece um plugin para lidar com arquivos de declaração de conteúdo e configura aliases para um desempenho ideal.

Passo 2: Configuração do seu projeto

Crie um arquivo de configuração para configurar os idiomas da sua aplicação:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Seus outros idiomas
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamento de middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desativar os logs do Intlayer no console e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a documentação de configuração.

Passo 3: Integrar o Intlayer na sua Configuração do Vite

Para integrar o Intlayer com o Analog, você precisa usar o plugin vite-intlayer.

Modifique seu arquivo vite.config.ts:

import { defineConfig } from "vite";import { intlayer } from "vite-intlayer";import analog from "@analogjs/platform";// https://vitejs.dev/config/export default defineConfig(() => ({  plugins: [    analog(),    intlayer(), // Adicione o plugin Intlayer  ],}));

O plugin intlayer() configura o Vite com o Intlayer. Ele lida com arquivos de declaração de conteúdo e configura aliases para um desempenho ideal.

Passo 4: Declarar seu Conteúdo

Crie e gerencie suas declarações de conteúdo para armazenar traduções:

Suas declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no diretório contentDir (por padrão, ./src) e correspondam à extensão do arquivo de declaração de conteúdo (por padrão, .content.{json,ts,tsx,js,jsx,mjs,cjs}).

Para mais detalhes, consulte a documentação de declaração de conteúdo.

Passo 5: Utilizar o Intlayer em seu Código

Para utilizar os recursos de internacionalização do Intlayer em toda a sua aplicação Analog, você precisa fornecer o Intlayer na configuração da sua aplicação.

import { ApplicationConfig } from "@angular/core";import { provideIntlayer } from "angular-intlayer";export const appConfig: ApplicationConfig = {  providers: [    provideIntlayer(), // Adicione o provedor Intlayer aqui  ],};

Então, você pode usar a função useIntlayer dentro de qualquer componente.

import { Component } from "@angular/core";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-home",  standalone: true,  template: `    <div class="content">      <h1>{{ content().title }}</h1>      <p>{{ content().congratulations }}</p>    </div>  `,})export default class HomeComponent {  content = useIntlayer("app");}

O conteúdo do Intlayer é retornado como um Signal, então você acessa os valores chamando o sinal: content().title.

(Opcional) Passo 6: Alterar o idioma do seu conteúdo

Para alterar o idioma do seu conteúdo, você pode usar a função setLocale fornecida pela função useLocale. Isso permite que você defina o idioma da aplicação e atualize o conteúdo adequadamente.

Crie um componente para alternar entre idiomas:

import { Component } from "@angular/core";import { CommonModule } from "@angular/common";import { useLocale } from "angular-intlayer";@Component({  selector: "app-locale-switcher",  standalone: true,  imports: [CommonModule],  template: `    <div class="locale-switcher">      <select        [value]="locale()"        (change)="setLocale($any($event.target).value)"      >        @for (loc of availableLocales; track loc) {          <option [value]="loc">{{ loc }}</option>        }      </select>    </div>  `,})export class LocaleSwitcherComponent {  localeCtx = useLocale();  locale = this.localeCtx.locale;  availableLocales = this.localeCtx.availableLocales;  setLocale = this.localeCtx.setLocale;}

Então, use este componente em suas páginas:

import { Component } from "@angular/core";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "../locale-switcher.component";@Component({  selector: "app-home",  standalone: true,  imports: [LocaleSwitcherComponent],  template: `    <app-locale-switcher></app-locale-switcher>    <div class="content">      <h1>{{ content().title }}</h1>      <p>{{ content().congratulations }}</p>    </div>  `,})export default class HomeComponent {  content = useIntlayer("app");}

Configurar TypeScript

O Intlayer usa o aumento de módulo (module augmentation) para obter benefícios do TypeScript e tornar sua base de código mais robusta.

Certifique-se de que sua configuração do TypeScript inclua os tipos autogerados.

{  // ... Suas configurações existentes do TypeScript  "include": [    // ... Suas configurações existentes do TypeScript    ".intlayer/**/*.ts", // Incluir os tipos autogerados  ],}

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite commitá-los no seu repositório Git.

Para fazer isso, você pode adicionar as seguintes instruções ao seu arquivo .gitignore:

#  Ignorar os arquivos gerados pelo Intlayer.intlayer

Extensão do VS Code

Para melhorar sua experiência de desenvolvimento com o Intlayer, você pode instalar a Extensão oficial do Intlayer para o VS Code.

Instalar a partir do VS Code Marketplace

Esta extensão fornece:

• Autocompletar para chaves de tradução.
• Detecção de erros em tempo real para traduções ausentes.
• Visualizações inline do conteúdo traduzido.
• Ações rápidas para criar e atualizar traduções facilmente.

Para mais detalhes sobre como usar a extensão, consulte a documentação da Extensão Intlayer para o VS Code.

Indo Além

Para ir além, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.