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

Índice

Por que Intlayer em vez de alternativas?

Comparado com soluções principais como astro-i18n ou i18next, Intlayer é uma solução que vem com otimizações integradas como:

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

Confira o modelo da aplicação no GitHub.

1. 1

   Instalar Dependências

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

   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 astro-intlayer vanilla-intlayer
   

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

2. 2

   Configurar seu Projeto

   Crie um arquivo de configuração para definir 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,
         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.

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

   astro.config.ts

   Copiar conteúdo

   Copiar código

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

   // @ts-check
   
   import { intlayer } from "astro-intlayer";
   import { defineConfig } from "astro/config";
   
   // https://astro.build/config
   export 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.

4. 4

   Declarar seu conteúdo

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

   src/app.content.ts

   Copiar conteúdo

   Copiar código

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

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

   Para mais informações, consulte a documentação de declaração de conteúdo.

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

   src/pages/[...locale]/index.astro

   Copiar conteúdo

   Copiar código

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

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

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

   src/pages/[...locale]/index.astro

   Copiar conteúdo

   Copiar código

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

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

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

   src/pages/sitemap.xml.ts

   Copiar conteúdo

   Copiar código

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

   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.

   src/pages/robots.txt.ts

   Copiar conteúdo

   Copiar código

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

   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" },
     });
   };
   

8. 15

   Extrair o conteúdo dos seus componentes

   Opcional

   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:

   intlayer.config.ts

   Copiar conteúdo

   Copiar código

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

   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;
   

   Comando de extraçãoCompilador Babel

   Execute o extrator para transformar seus componentes e extrair o conteúdo

   bash

   Copiar conteúdo

   Copiar código

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

   npx intlayer extract
   

   Since v9, the intlayerCompiler is included in the intlayer plugin. So you don't need to add it manually.

   Atualize seu vite.config.ts para incluir o plugin intlayerCompiler:

   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, intlayerCompiler } from "vite-intlayer";
   
   export default defineConfig({
     plugins: [
       intlayer(),
       intlayerCompiler(), // Adds the compiler plugin
     ],
   });
   

   bash

   Copiar conteúdo

   Copiar código

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

   npm run build # Ou npm run dev
   

   ---

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.

Aprofunde seu conhecimento

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