Como tornar multilíngue (i18n) uma aplicação Vite e React existente depois de pronta (guia i18n 2026)

Veja o Modelo de Aplicação no GitHub.

Índice

Por que é difícil internacionalizar uma aplicação existente?

Se você já tentou adicionar vários idiomas a um app que foi construído para apenas um, você conhece a dor. Não é apenas "difícil", é tedioso. Você tem que vasculhar cada arquivo, caçar cada string de texto e movê-las para arquivos de dicionário separados.

Depois vem a parte arriscada: substituir todo esse texto por hooks de código sem quebrar o layout ou a lógica. É o tipo di trabalho que interrompe o desenvolvimento de novas funcionalidades por semanas e parece uma refatoração interminável.

O que é o Compilador Intlayer?

O Compilador Intlayer foi criado para pular esse trabalho braçal manual. Em vez de você extrair strings manualmente, o compilador faz isso por você. Ele escaneia seu código, encontra o texto e usa IA para gerar os dicionários nos bastidores. Depois, ele modifica seu código durante o build para injetar os hooks de i18n necessários. Basicamente, você continua escrevendo seu app como se fosse de um único idioma, e o compilador cuida da transformação multilíngue automaticamente.

Doc Compilador: /pt/doc/compiler

Limitações

Como o compilador realiza análise e transformação de código (inserindo hooks e gerando dicionários) em tempo de compilação, ele pode reduzir a velocidade do processo di build da sua aplicação.

Para mitigar esse impacto durante o desenvolvimento, você pode configurar o compilador para rodar no modo 'build-only' ou desativá-lo quando não for necessário.

Guia Passo a Passo para Configurar o Intlayer em uma Aplicação Vite e React

Passo 1: Instalar Dependências

Instale os pacotes necessários usando npm:

npm install intlayer react-intlayernpm install vite-intlayer --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.

• react-intlayer O pacote que integra o Intlayer com a aplicação React. Ele fornece provedores de contexto e hooks para internacionalização no React.

• vite-intlayer Inclui o plugin Vite para integrar o Intlayer com o Vite bundler, bem como middleware para detectar o idioma preferido do usuário, gerenciar cookies e lidar com redirecionamento de URL.

Passo 2: Configurar 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,      Locales.PORTUGUESE,    ],    defaultLocale: Locales.ENGLISH,  },  compiler: {    /**     * Indica se o compilador deve ser habilitado.     */    enabled: true,    /**     * Diretório de saída para os dicionários optimizados.     */    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,    /**     * Inserir apenas o conteúdo no arquivo gerado, sem chave.     */    noMetadata: false,    /**     * Prefixo da chave do dicionário     */    dictionaryKeyPrefix: "", // Remove base prefix    /**     * Indica se os componentes devem ser salvos após serem transformados.     * Dessa forma, o compilador pode ser executado apenas uma vez para transformar o app e depois removido.     */    saveComponents: false,  },  ai: {    provider: "openai",    model: "gpt-5-mini",    apiKey: process.env.OPEN_AI_API_KEY,    applicationContext: "Este é um app de mapas", // Nota: você pode personalizar esta descrição do app  },};export default config;

Nota: Certifique-se de ter sua OPEN_AI_API_KEY definida em suas variáveis de ambiente.

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

Adicione o plugin intlayer na sua configuração.

import { defineConfig } from "vite";import react from "@vitejs/plugin-react-swc";import { intlayer, intlayerCompiler } from "vite-intlayer";// https://vitejs.dev/config/export default defineConfig({  plugins: [react(), intlayer(), intlayerCompiler()],});

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

O plugin Vite intlayerCompiler() é usado para extrair conteúdo do componente e escrever os arquivos .content.

Passo 4: Compilar seu código

Basta escrever seus componentes com strings hardcoded no seu idioma padrão. O compilador cuida do resto.

Exemplo de como sua página pode ficar:

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt="Logo Vite" />       </a>       <a href="https://react.dev" target="_blank">         <img src={reactLogo} className="logo react" alt="Logo React" />       </a>     </div>     <h1>Vite + React</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         a contagem é {count}       </button>       <p>         Edite <code>src/App.tsx</code> e salve para testar HMR       </p>     </div>     <p className="read-the-docs">       Clique nos logos do Vite e React para saber mais     </p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

{ key: "app-content", content: {   nodeType: "translation",   translation: {     en: {       viteLogo: "Vite logo",       reactLogo: "React logo",       title: "Vite + React",       countButton: "count is",       editMessage: "Edit",       hmrMessage: "and save to test HMR",       readTheDocs: "Click on the Vite and React logos to learn more",     },     pt: {       viteLogo: "Logo Vite",       reactLogo: "Logo React",       title: "Vite + React",       countButton: "a contagem é",       editMessage: "Editar",       hmrMessage: "e salve para testar HMR",       readTheDocs: "Clique nos logos do Vite e React para saber mais",     },   } }}

import { useState, type FC } from "react";import reactLogo from "./assets/react.svg";import viteLogo from "/vite.svg";import "./App.css";import { IntlayerProvider, useIntlayer } from "react-intlayer";const AppContent: FC = () => { const [count, setCount] = useState(0); const content = useIntlayer("app-content"); return (   <>     <div>       <a href="https://vitejs.dev" target="_blank">         <img src={viteLogo} className="logo" alt={content.viteLogo.value} />       </a>       <a href="https://react.dev" target="_blank">         <img           src={reactLogo}           className="logo react"           alt={content.reactLogo.value}         />       </a>     </div>     <h1>{content.title}</h1>     <div className="card">       <button onClick={() => setCount((count) => count + 1)}>         {content.countButton} {count}       </button>       <p>         {content.editMessage} <code>src/App.tsx</code> {content.hmrMessage}       </p>     </div>     <p className="read-the-docs">{content.readTheDocs}</p>   </> );};const App: FC = () => ( <IntlayerProvider>   <AppContent /> </IntlayerProvider>);export default App;

• IntlayerProvider é usado para fornecer o idioma aos componentes aninhados.

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

Para alterar o idioma do seu conteúdo, você pode usar a função setLocale fornecida pelo hook useLocale. Esta função permite que você defina o idioma da aplicação e atualize o conteúdo adequadamente.

import type { FC } from "react";import { Locales } from "intlayer";import { useLocale } from "react-intlayer";const LocaleSwitcher: FC = () => {  const { setLocale } = useLocale();  return (    <button onClick={() => setLocale(Locales.English)}>      Alterar idioma para Inglês    </button>  );};

Para aprender mais sobre o hook useLocale, consulte a documentação.

(Opcional) Etapa 7: Preencher traduções ausentes

Intlayer fornece uma ferramenta CLI para ajudá-lo a preencher as traduções ausentes. Você pode usar o comando intlayer para testar e preencher as traduções ausentes do seu código.

npx intlayer test         # Testa se há traduções ausentes

npx intlayer fill         # Preencher traduções ausentes

Para mais detalhes, consulte a documentação da CLI

(Opcional) Sitemap e robots.txt (geração no build)

A Intlayer expõe utilitários - generateSitemap e getMultilingualUrls - para formatar um sitemap.xml multilíngue e um robots.txt prontos para crawlers e os gravar automaticamente em public/. Normalmente corre um pequeno script Node antes do Vite (por exemplo hooks npm predev / prebuild) para que os ficheiros existam no build ou no servidor de desenvolvimento.

Sitemap

O gerador de sitemaps da Intlayer respeita as suas línguas e inclui os metadados habituais.

O sitemap suporta o espaço de nomes xhtml:link (hreflang). Em vez de listar apenas URLs soltas, a Intlayer liga de forma bidireccional todas as versões localizadas de cada página (por exemplo /about, /fr/about ou /about?lang=fr consoante o modo de rotas).

Robots.txt

Use getMultilingualUrls para que as regras Disallow cubram todas as variantes localizadas de caminhos sensíveis.

1. Criar generate-seo.mjs na raiz do projeto

import fs from "fs";import path from "path";import { fileURLToPath } from "url";import { generateSitemap, getMultilingualUrls } from "intlayer";const __dirname = path.dirname(fileURLToPath(import.meta.url));const SITE_URL = (process.env.SITE_URL || "http://localhost:5173").replace(  /\/$/,  "");const pathList = [  { path: "/", changefreq: "daily", priority: 1.0 },  { path: "/about", changefreq: "monthly", priority: 0.7 },];const sitemapXml = generateSitemap(pathList, { siteUrl: SITE_URL });fs.writeFileSync(path.join(__dirname, "public", "sitemap.xml"), sitemapXml);const getAllMultilingualUrls = (urls) =>  urls.flatMap((url) => Object.values(getMultilingualUrls(url)));const disallowedPaths = getAllMultilingualUrls(["/admin", "/private"]);const robotsTxt = [  "User-agent: *",  "Allow: /",  ...disallowedPaths.map((path) => `Disallow: ${path}`),  "",  `Sitemap: ${SITE_URL}/sitemap.xml`,].join("\n");fs.writeFileSync(path.join(__dirname, "public", "robots.txt"), robotsTxt);console.log("SEO files generated successfully.");

O pacote intlayer tem de estar instalado. Defina SITE_URL no ambiente em produção (por exemplo na CI).

Prefira generate-seo.mjs para ESM no Node. Se usar generate-seo.js, garanta "type": "module" no package.json ou execute o Node com ESM.

2. Executar o script antes do Vite

{  "scripts": {    "dev": "vite",    "prebuild": "node generate-seo.mjs",    "build": "vite build",    "preview": "vite preview"  }}

Ajuste os comandos se usar pnpm ou yarn. Também pode invocar o script a partir da CI ou de outro passo do pipeline.

Configuração do Git

É recomendado 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 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 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.
• Pré-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 do Intlayer para VS Code.

Indo Além

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