Receba notificações sobre os próximos lançamentos de Intlayer
    Criação:2024-03-07Última atualização:2025-10-03

    Começando a Internacionalizar (i18n) com Intlayer e Astro

    Veja o Modelo de Aplicação no GitHub.

    O que é Intlayer?

    Intlayer é uma biblioteca inovadora e open-source de internacionalização (i18n) 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 no nível do componente.
    • Localizar dinamicamente metadados, rotas e conteúdo.
    • Garantir suporte ao TypeScript com tipos autogerados, melhorando o autocompletar e a detecção de erros.
    • Aproveitar recursos avançados, como detecção e troca dinâmica de localidade.

    Guia Passo a Passo para Configurar o Intlayer no Astro

    Passo 1: Instalar Dependências

    Instale os pacotes necessários usando seu gerenciador de pacotes:

    npm install intlayer astro-intlayer# Opcional: adicionar suporte a React islandnpm install react react-dom react-intlayer @astrojs/react

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

    • astro-intlayer Inclui o plugin de integração do Astro para integrar o Intlayer com o empacotador Vite, assim como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

    Passo 2: Configuração do seu projeto

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

    intlayer.config.ts
    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 via middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desabilitar 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: Integre o Intlayer na sua Configuração do Astro

    Adicione o plugin intlayer na sua configuração.

    astro.config.ts
    // @ts-checkimport { intlayer } from "astro-intlayer";import { defineConfig } from "astro/config";// https://astro.build/configexport default defineConfig({  integrations: [intlayer()],});

    O plugin de integração intlayer() para Astro é usado para integrar o Intlayer com o Astro. Ele garante a construção dos arquivos de declaração de conteúdo e os monitora no modo de desenvolvimento. Define variáveis de ambiente do Intlayer dentro da aplicação Astro. Além disso, fornece aliases para otimizar o desempenho.

    Passo 4: Declare Seu Conteúdo

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

    src/app.content.tsx
    import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";const appContent = {  key: "app",  content: {    title: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",    }),  },} satisfies Dictionary;export default appContent;

    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,mjx,cjs,cjx}).

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

    Passo 5: Use seu conteúdo no Astro

    Você pode consumir dicionários diretamente em arquivos .astro usando os helpers principais exportados pelo intlayer.

    src/pages/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";import appContent from "../app.content";const { title } = getIntlayer('app');---<html lang="en">  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <title>{title}</title>  </head>  <body>    <h1>{title}</h1>  </body></html>

    Passo 6: Roteamento localizado

    Crie um segmento de rota dinâmica para servir páginas localizadas, por exemplo src/pages/[locale]/index.astro:

    src/pages/[locale]/index.astro
    <!-- astro -->---import { getIntlayer } from "intlayer";const { title } = getIntlayer('app');---<h1>{title}</h1>

    A integração do Astro adiciona um middleware Vite durante o desenvolvimento que ajuda com o roteamento consciente de localidade e definições de ambiente. Você ainda pode criar links entre localidades usando sua própria lógica, ou funções utilitárias como getLocalizedUrl do intlayer.

    Passo 7: Continue usando seu framework favorito

    Continue usando seu framework favorito para construir sua aplicação.

    Configurar TypeScript

    Intlayer usa a ampliação de módulos para obter os benefícios do TypeScript e tornar sua base de código mais robusta.

    Autocompletion

    Translation error

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

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

    Configuração do Git

    É recomendado ignorar os arquivos gerados pelo Intlayer. Isso permite evitar que eles sejam commitados no seu repositório Git.

    Para 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 VS Code.

    Instalar no Marketplace do VS Code

    Esta extensão oferece:

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

    Ir Além

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

    Histórico da Documentação

    Versão Data Alterações
    6.2.0 2025-10-03 Atualização para integração com Astro, configuração, uso
    Tanstack Start
    React CRA
    Receba notificações sobre os próximos lançamentos de Intlayer