Autor:
    Aymeric PINEAU
    Criação:2024-03-07Última atualização:2026-05-31

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

    www.youtube.com
    ide.intlayer.org
    intlayer-vite-react-template.vercel.app

    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

    1. Instalar Dependências

      Instale os pacotes necessários usando npm:

      bash
      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
      npm install intlayer react-intlayer
npm install vite-intlayer --save-dev

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

    2. Configurar 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,
      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.

    3. Integrar o Intlayer na sua Configuração do Vite

      Adicione o plugin intlayer na sua configuração.

      vite.config.ts
      import { defineConfig } from "vite";
import react from "@vitejs/plugin-react-swc";
import { intlayer } from "vite-intlayer";

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    react(),
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});
      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.
      Desde Intlayer v9, o compilador está incluído diretamente no plugin intlayer() e é ativado automaticamente quando compiler.enabled é definido com um caminho compiler.output. Registrar intlayerCompiler() separadamente, como mostrado abaixo, agora é opcional — ele se deduplica se também for adicionado. Veja as notas de lançamento v9.

    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:

      src/App.tsx
      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;
      i18n/app-content.content.json
      {
  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",
      },
    }
  }
}
      src/App.tsx
      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.

    5. Alterar o idioma do seu conteúdo

      Opcional

      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.

      src/components/LocaleSwitcher.tsx
      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.

    6. Preencher traduções ausentes

      Opcional

      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.

      bash
      npx intlayer test         # Testa se há traduções ausentes
      bash
      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

    generate-seo.mjs
    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

    package.json
    {
  "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:

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

    React Router v7 (fs-routes)Vite e Vue