Traduza o seu site Astro + Vanilla JS com o Intlayer | Internacionalização (i18n)

Índice

O que é o 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 metadversas, rotas e conteúdo dinamicamente.
• Garantir suporte TypeScript: Com tipos gerados automaticamente para melhor preenchimento automático e detecção de erros.
• Beneficiar de recursos avançados: Como detecção dinâmica de idioma e troca de idioma.

Guia passo a passo para configurar o Intlayer no Astro + Vanilla JS

Confira o modelo da aplicação no GitHub.

Passo 1: Instalar Dependências

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

npm install intlayer astro-intlayer vanilla-intlayernpx intlayer init

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

• astro-intlayer Inclui o plugin de integração do Astro para vincular o Intlayer ao bundler Vite, bem como o middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamentos de URL.

• vanilla-intlayer Um pacote para integrar o Intlayer em aplicações Vanilla JavaScript / TypeScript. Ele fornece um singleton Pub/Sub (IntlayerClient) e ajudantes baseados em callbacks (useIntlayer, useLocale, etc.), permitindo que qualquer parte das suas tags <script> do Astro responda a mudanças de idioma sem a necessidade de um framework de UI.

Passo 2: Configurar seu Projeto

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

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      Locales.PORTUGUESE,      // Seus outros idiomas    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Através deste arquivo de configuração, você pode configurar URLs localizadas, redirecionamentos de middleware, nomes de cookies, localização e extensões de declarações de conteúdo, desativar 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 Astro

Adicione o plugin intlayer à sua configuração do Astro. Para Vanilla JS, nenhuma integração adicional de framework de UI é necessária.

// @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() é usado para integrar o Intlayer ao Astro. Ele garante a geração dos arquivos de declaração de conteúdo e os monitora em modo de desenvolvimento. Ele define variáveis de ambiente do Intlayer dentro da aplicação Astro e fornece aliases para otimizar o desempenho.

Passo 4: Declarar seu conteúdo

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

import { t, type Dictionary } from "intlayer";const appContent = {  key: "app",  content: {    greeting: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola mundo",      pt: "Olá Mundo",    }),    description: t({      en: "Welcome to my multilingual Astro site.",      fr: "Bienvenue sur mon site Astro multilingue.",      es: "Bienvenido a mi sitio Astro multilingüe.",      pt: "Bem-vindo ao meu site Astro multilíngue.",    }),    switchLocale: t({      en: "Switch language:",      fr: "Changer de langue :",      es: "Cambiar idioma:",      pt: "Mudar idioma:",    }),  },} satisfies Dictionary;export default appContent;

As declarações de conteúdo podem ser definidas em qualquer lugar da sua aplicação, desde que estejam incluídas no 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 informações, consulte a documentação de declaração de conteúdo.

Passo 5: Usar o conteúdo no Astro

Com Vanilla JS, toda a renderização no lado do servidor acontece diretamente nos arquivos .astro usando getIntlayer. Posteriormente, um bloco <script> inicializa o vanilla-intlayer no cliente para habilitar a troca de idioma.

---import {  getIntlayer,  getLocaleFromPath,  getLocalizedUrl,  getPrefix,  getLocaleName,  localeMap,  locales,  defaultLocale,  getPathWithoutLocale,  type LocalesValues,} from "intlayer";export const getStaticPaths = () => {  return localeMap(({ locale }) => ({    params: { locale: getPrefix(locale).localePrefix },  }));};const locale = getLocaleFromPath(Astro.url.pathname) as LocalesValues;const pathWithoutLocale = getPathWithoutLocale(Astro.url.pathname);const { greeting, description, switchLocale } = getIntlayer("app", locale);---<!doctype html><html lang={locale} dir={getHTMLTextDir(locale)}>  <head>    <meta charset="utf-8" />    <meta name="viewport" content="width=device-width" />    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />    <title>{greeting}</title>    <!-- Link Canônico -->    <link      rel="canonical"      href={new URL(getLocalizedUrl(Astro.url.pathname, locale), Astro.site)}    />    <!-- Links Hreflang -->    {      localeMap(({ locale: mapLocale }) => (        <link          rel="alternate"          hreflang={mapLocale}          href={new URL(            getLocalizedUrl(Astro.url.pathname, mapLocale),            Astro.site          )}        />      ))    }    <link      rel="alternate"      hreflang="x-default"      href={new URL(        getLocalizedUrl(Astro.url.pathname, defaultLocale),        Astro.site      )}    />  </head>  <body>    <main>      <h1 id="greeting">{greeting}</h1>      <p id="description">{description}</p>      <div class="locale-switcher">        <span class="switcher-label">{switchLocale}</span>        <div class="locale-buttons">          {            locales.map((localeItem) => (              <a                href={localeItem === locale ? undefined : getLocalizedUrl(pathWithoutLocale, localeItem)}                class={`locale-btn ${localeItem === locale ? "active" : ""}`}                data-locale={localeItem}                aria-disabled={localeItem === locale}              >                {getLocaleName(localeItem)}              </a>            ))          }        </div>      </div>    </main>  </body></html>

Se você quiser usar seu conteúdo em un atributo de string, como alt, title, href, aria-label, etc., você pode usar o valor da função, como:

html

Copiar conteúdo

Copiar código

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

<img src="{content.image.src.value}" alt="{content.image.value}" /><img src="{content.image.src.toString()}" alt="{content.image.toString()}" /><img src="{String(content.image.src)}" alt="{String(content.image)}" />

Nota sobre a configuração de roteamento: A estrutura de diretórios que você usa depende da configuração middleware.routing no intlayer.config.ts:

• prefix-no-default (padrão): mantém o idioma padrão na raiz (sem prefixo) e adiciona prefixos aos outros. Use [...locale] para capturar todos os casos.
• prefix-all: todos os URLs recebem um prefixo de idioma. Você pode usar o padrão [locale] se não precisar lidar com a raiz separadamente.
• search-param ou no-prefix: não são necessários diretórios de idioma. O idioma é tratado via parâmetros de consulta ou cookies.

Passo 6: Adicionar um Seletor de Idioma

No Astro com Vanilla JS, o seletor de idioma é renderizado no servidor como links comuns e hidratado no cliente via um bloco <script>. Quando um usuário clica em um link de idioma, o vanilla-intlayer define o cookie de idioma via setLocale antes de navegar para a URL localizada.

<!-- Inclua a marcação do lado do servidor do passo 5 acima --><script>  import { installIntlayer, useLocale } from "vanilla-intlayer";  import { getLocaleFromPath, getLocalizedUrl, type LocalesValues } from "intlayer";  // Inicializa o Intlayer no cliente com a localidade retirada do caminho atual  const locale = getLocaleFromPath(window.location.pathname);  installIntlayer({ locale: locale as LocalesValues });  const { setLocale } = useLocale({    onLocaleChange: (newLocale: LocalesValues) => {      window.location.href = getLocalizedUrl(window.location.pathname, newLocale);    },  });  // Vincula eventos de clique aos links do seletor de idioma  const localeLinks = document.querySelectorAll("[data-locale]");  localeLinks.forEach((link) => {    link.addEventListener("click", (e) => {      const localeValue = link.getAttribute("data-locale") as LocalesValues;      if (localeValue && localeValue !== locale) {        e.preventDefault();        setLocale(localeValue);      }    });  });</script>

Nota sobre persistência: installIntlayer inicializa o singleton do Intlayer com a localidade definida pelo servidor. useLocale com onLocaleChange garante que o cookie de idioma seja definido antes de navegar via middleware, para que a preferência de idioma do usuário seja lembrada em visitas futuras.

Nota sobre Melhoria Progressiva: Os links no seletor de idioma funcionarão como tags <a> padrão mesmo sem JavaScript. Quando o JavaScript estiver disponível, as chamadas para setLocale atualizarão o cookie antes de navegar, garantindo que o middleware execute o redirecionamento correto.

Passo 7: Sitemap e Robots.txt

O Intlayer oferece utilitários para criar dinamicamente o seu sitemap localizado e os arquivos robots.txt.

Sitemap

O Intlayer vem com um gerador de sitemap integrado para ajudá-lo a criar facilmente um sitemap para sua aplicação. Ele cuida das rotas localizadas e adiciona os metadados necessários para os mecanismos de busca.

O sitemap gerado pelo Intlayer suporta o namespace xhtml:link (Hreflang XML Extensions). Ao contrário dos geradores de sitemap padrão que apenas listam URLs brutos, o Intlayer cria automaticamente os links bidirecionais necessários entre todas as versões de idioma de uma página (por exemplo, /about, /about?lang=fr e /about?lang=es). Isso garante que os mecanismos de busca indexem e sirvam corretamente a versão de idioma certa para o público certo.

Crie src/pages/sitemap.xml.ts para gerar um sitemap que inclua todas as suas rotas localizadas.

import type { APIRoute } from "astro";import { generateSitemap, type SitemapUrlEntry } from "intlayer";const pathList: SitemapUrlEntry[] = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const SITE_URL = import.meta.env.SITE ?? "http://localhost:4321";export const GET: APIRoute = async ({ site }) => {  const xmlOutput = generateSitemap(pathList, { siteUrl: SITE_URL });  return new Response(xmlOutput, {    headers: { "Content-Type": "application/xml" },  });};

Robots.txt

Crie src/pages/robots.txt.ts para controlar o rastreamento dos motores de busca.

import type { APIRoute } from "astro";import { getMultilingualUrls } from "intlayer";const getAllMultilingualUrls = (urls: string[]) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)) as string[]);const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);export const GET: APIRoute = ({ site }) => {  const robotsTxt = [    "User-agent: *",    "Allow: /",    ...disallowedPaths.map((path) => `Disallow: ${path}`),    "",    `Sitemap: ${new URL("/sitemap.xml", site).href}`,  ].join("\n");  return new Response(robotsTxt, {    headers: { "Content-Type": "text/plain" },  });};

Configuração do TypeScript

O Intlayer usa o aumento de módulos (module augmentation) para aproveitar o TypeScript, tornando sua base de código mais robusta.

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

{  // ... sua configuração existente do TypeScript  "include": [    // ... sua configuração existente do TypeScript    ".intlayer/**/*.ts", // Incluir tipos gerados automaticamente  ],}

Configuração do Git

Recomenda-se ignorar os arquivos gerados pelo Intlayer. Isso evita committá-los no seu repositório Git.

Para fazer isso, adicione 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.

Instalação pelo VS Code Marketplace

Esta extensão fornece:

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

Para mais informações sobre o uso da extensão, consulte a documentação da Extensão do VS Code.

(Opcional) Passo 15: Extrair o conteúdo dos seus componentes

Se você tiver uma base de código existente, transformar milhares de arquivos pode ser demorado.

Para facilitar esse processo, o Intlayer propõe um compilador / extrator para transformar seus componentes e extrair o conteúdo.

Para configurá-lo, você pode adicionar uma seção compiler no seu arquivo intlayer.config.ts:

import { type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  // ... Resto da sua configuração
  compiler: {
    /**
     * Indica se o compilador deve ser ativado.
     */
    enabled: true,

    /**
     * Define o caminho dos arquivos de saída
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Indica se os componentes devem ser salvos após serem transformados. Dessa forma, o compilador pode ser executado apenas uma vez para transformar o aplicativo e depois removido.
     */
    saveComponents: false,

    /**
     * Prefixo da chave do dicionário
     */
    dictionaryKeyPrefix: "",
  },
};

export default config;

npx intlayer extract

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Adiciona o plugin do compilador ],});

npm run build # Ou npm run dev

Aprofunde seu conhecimento

Se quiser saber mais, você também pode implementar o Editor Visual ou usar o CMS para externalizar seu conteúdo.