Traduza seu site Angular 21 (Vite) usando Intlayer | Internacionalização (i18n)

Índice

O que é Intlayer?

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

Com Intlayer, você pode:

• Gerenciar traduções facilmente usando dicionários declarativos no nível do componente.
• Localizar metadados dinamicamente, rotas e conteúdo.
• Garantir o suporte ao TypeScript com tipos gerados automaticamente, melhorando o preenchimento automático e a detecção de erros.
• Beneficiar-se de recursos avançados, como detecção dinâmica e alternância de localidade.

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

Veja o Modelo de Aplicação no GitHub.

Passo 1: Instalar Dependências

Instale os pacotes necessários usando o npm:

npm install intlayer angular-intlayernpm install @angular-builders/custom-esbuild --save-devnpx 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 à aplicação Angular. Ele fornece provedores de contexto e hooks para internacionalização Angular.

• @angular-builders/custom-esbuild Necessário para personalizar a configuração esbuild da Angular CLI.

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;

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

Passo 3: Integrar o Intlayer na sua Configuração Angular

Para integrar o Intlayer com o Angular CLI, você precisa usar um builder personalizado. Este guia assume que você está usando Vite/esbuild (padrão para projetos Angular 21).

Primeiro, modifique seu angular.json para usar o construtor esbuild personalizado. Atualize as configurações build e serve:

{  "projects": {    "your-app-name": {      "architect": {        "build": {          "builder": "@angular-builders/custom-esbuild:application", // replace "@angular/build:application"          "options": {            "define": {              "process.env": "{}",            },            "plugins": ["./esbuild.plugins.ts"],            "browser": "src/main.ts",            // ...          },        },        "serve": {          "builder": "@angular-builders/custom-esbuild:dev-server", // replace "@angular/build:dev-server"          "options": {            "prebundle": {              "exclude": [                "intlayer",                "angular-intlayer",                "@intlayer/config/built",                "@intlayer/core"              ]          },        },      },    },  },}

Certifique-se de substituir your-app-name pelo nome real do seu projeto em angular.json.

Em seguida, crie um arquivo esbuild.plugins.ts na raiz do seu projeto:

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

A função intlayerEsbuildPlugin configura o esbuild com o Intlayer. Ela injeta o plugin para gerenciar arquivos de declaração de conteúdo e configura alias para desempenho ideal.

Usuários do NX: Os construtores Angular do NX carregam arquivos de plug-in por meio da resolução ESM nativa do Node e não compilam arquivos de plug-in TypeScript dinamicamente. Use um arquivo .mjs e atualize a referência plugins no angular.json de acordo:

esbuild.plugins.mjs

Copiar conteúdo

Copiar código

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

import { intlayerEsbuildPlugin } from "angular-intlayer/esbuild";export default [intlayerEsbuildPlugin()];

Em seguida, no angular.json, aponte para "./esbuild.plugins.mjs" em vez de "./esbuild.plugins.ts".

Passo 4: Declare 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 de sua aplicação, desde que sejam incluídas no diretório contentDir (por padrão, ./src). E que 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: Utilize o Intlayer no seu Código

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

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

Em seguida, você pode usar a função useIntlayer em qualquer componente.

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

E no seu template:

<div class="content">  <h1>{{ content().title }}</h1>  <p>{{ content().congratulations }}</p></div>

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

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

Para mudar 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 do aplicativo e atualize o conteúdo de acordo.

Crie um componente para alternar entre os 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;}

Em seguida, use este componente no seu app.component.ts:

import { Component } from "@angular/core";import { RouterOutlet } from "@angular/router";import { useIntlayer } from "angular-intlayer";import { LocaleSwitcherComponent } from "./locale-switcher.component";@Component({  selector: "app-root",  standalone: true,  imports: [RouterOutlet, LocaleSwitcherComponent],  templateUrl: "./app.component.html",  styleUrl: "./app.component.css",})export class AppComponent {  content = useIntlayer("app");}

Configurar TypeScript

O Intlayer usa o aumento de módulo para obter os benefícios do TypeScript e tornar sua base de código mais forte.

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

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

Configuração do Git

É recomendável ignorar os arquivos gerados pelo Intlayer. Isso permite que você evite confirmá-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 Intlayer VS Code Extension.

Instalar do VS Code Marketplace

Esta extensão oferece:

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

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

Vá além

Para ir mais longe, você pode implementar o editor visual ou externalizar o seu conteúdo usando o CMS.