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

Sumário

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como ngx-translate ou angular-l10n, Intlayer é uma solução que vem com otimizações integradas como:

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

Veja o Modelo de Aplicação no GitHub.

1. 1

   Instalar Dependências

   Instale os pacotes necessários usando npm:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npx intlayer init --interactive
   

   a flag --interactive é opcional. Use intlayer-cli init se você for um agente de IA.

   Este comando detectará seu ambiente e instalará os pacotes necessários. Por exemplo:

   bash

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   npm install intlayer angular-intlayer vite-intlayer
   

   • 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.

2. 2

   Configuração do seu projeto

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

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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.

3. 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:

   vite.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   import { defineConfig } from "vite";
   import { intlayer } from "vite-intlayer";
   import analog from "@analogjs/platform";
   
   // https://vitejs.dev/config/
   export default defineConfig(() => ({
     plugins: [
       analog(),
       intlayer({
         proxy: {
           ignore: (req) => req.url?.startsWith("/api"),
         },
       }),
     ],
   }));
   

   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.

4. 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,md,mdx,yaml,yml}).

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

5. 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.

   src/app/app.config.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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.

   src/app/pages/index.page.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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.

6. 6

   Alterar o idioma do seu conteúdo

   Opcional

   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:

   src/app/locale-switcher.component.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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:

   src/app/pages/index.page.ts

   Copiar conteúdo

   Copiar código

   Copiar o código para a área de transferência

   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 mais longe, você pode implementar o editor visual ou externalizar seu conteúdo usando o CMS.

Perguntas Frequentes