Autor:
    Aymeric PINEAU
    Criação:2026-03-31Última atualização:2026-08-30

    Traduza o seu site Vanilla JS usando Intlayer | Internacionalização (i18n)

    ide.intlayer.org
    intlayer-vanilla-template.vercel.app

    Índice

    Por que Intlayer em vez de alternativas?

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

    O Intlayer é otimizado para funcionar perfeitamente com Vanilla JavaScript, oferecendo gerenciamento de conteúdo independente de estrutura, suporte a TypeScript e todos os recursos necessários para dimensionar a internacionalização (i18n).

    Em vez de carregar arquivos JSON enormes em suas páginas, carregue apenas o conteúdo necessário. O Intlayer ajuda a reduzir o tamanho do bundle e das páginas em até 50%.

    Definir o escopo do conteúdo do seu aplicativo facilita a manutenção de aplicativos de grande escala. Você pode duplicar ou excluir uma única pasta de recursos sem o fardo mental de revisar toda a base de código de seu conteúdo. Além disso, o Intlayer é totalmente tipado (fully typed) para garantir a precisão do seu conteúdo.

    A co-localização de conteúdo reduz o contexto necessário pelos Large Language Models (LLMs). O Intlayer também vem com um conjunto de ferramentas, como uma CLI para testar traduções ausentes,LSP, MCP, e agent skills, para tornar a experiência do desenvolvedor (DX) ainda mais tranquila para os agentes de IA.

    Use a automação para traduzir seu pipeline de CI/CD usando o LLM de sua escolha às custas de seu provedor de IA. O Intlayer também oferece um compilador para automatizar a extração de conteúdo, bem como uma plataforma web para ajudar a traduzir em segundo plano.

    Conectar arquivos JSON enormes a componentes pode levar a problemas de desempenho e reatividade. O Intlayer otimiza o carregamento do seu conteúdo no momento da construção.

    Mais do que apenas uma solução i18n, o Intlayer fornece um [editor visual] auto-hospedado(/pt/doc/concept/editor)* e um *CMS completo para ajudá-lo a gerenciar seu conteúdo multilíngue em tempo real, facilitando a colaboração com tradutores, redatores e outros membros da equipe. O conteúdo pode ser armazenado local e/ou remotamente.

    Guia Passo a Passo para Configurar o Intlayer numa Aplicação Vanilla JS

    1. Instalar Dependências

      Instale os pacotes necessários utilizando o npm:

      bash
      # Gerar um bundle standalone do intlayer e vanilla-intlayer
# Este ficheiro será importado no seu ficheiro HTML
npx intlayer standalone --packages intlayer vanilla-intlayer --outfile intlayer.js

# Inicializar o intlayer com o ficheiro de configuração
npx intlayer init --no-gitignore

# Construir os dicionários
npx intlayer build

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

      • vanilla-intlayer O pacote que integra o Intlayer com aplicações puras JavaScript / TypeScript. Fornece um singleton pub/sub (IntlayerClient) e auxiliares baseados em callbacks (useIntlayer, useLocale, etc.) para que qualquer parte da sua aplicação possa reagir a mudanças de idioma sem depender de uma framework de UI.

      A exportação de empacotamento (bundling) do CLI intlayer standalone produz uma build otimizada através do tree-shaking de pacotes não utilizados, idiomas e lógica não essencial (como redirecionamentos ou prefixos) específica para a sua configuração.

    2. Configuração do seu projeto

      Arquitetura

      Nesta arquitetura, o núcleo intlayer fornece APIs JavaScript para declarar e consumir dicionários em ambientes padrão de JavaScript ou TypeScript sem um framework frontend.

      bash
      .
├── src
│   ├── app.content.mjs
│   └── main.js
├── index.html
├── intlayer.config.mjs
└── package.json

      Configuração

      Crie um ficheiro 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 ficheiro de configuração, pode configurar URLs localizados, redirecionamento de middleware, nomes de cookies, a localização e extensão das suas declarações de conteúdo, desativar logs do Intlayer na consola e muito mais. Para uma lista completa de parâmetros disponíveis, consulte a documentação de configuração.

    3. Importar o bundle no seu HTML

      Depois de gerar o bundle intlayer.js, pode importá-lo no seu ficheiro HTML:

      index.html
      <!DOCTYPE html>
<html lang="pt">
  <head>
    <meta charset="UTF-8" />

    <!-- Importar o bundle -->
    <script src="./intlayer.js" defer></script>
    <!-- Importar o seu script principal -->
    <script src="./src/main.js" defer></script>
  </head>
  <body>
    <h1 id="title"></h1>
    <p class="read-the-docs"></p>
  </body>
</html>

      O bundle expõe o Intlayer e o VanillaIntlayer como objetos globais no window.

    4. Bootstrapper do Intlayer no seu ponto de entrada

      No seu src/main.js, chame installIntlayer() antes de qualquer conteúdo ser renderizado, para que o singleton global de idioma esteja pronto.

      src/main.js
      const { installIntlayer } = window.VanillaIntlayer;

// Deve ser chamado antes de renderizar qualquer conteúdo i18n.
installIntlayer();

      Se também pretender utilizar o renderizador de markdown, chame installIntlayerMarkdown():

      src/main.js
      const { installIntlayer, installIntlayerMarkdown } = window.VanillaIntlayer;

installIntlayer();
installIntlayerMarkdown();

    5. Declarar o Seu Conteúdo

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

      src/app.content.ts
      import { insert, t, type Dictionary } from "intlayer";

const appContent = {
  key: "app",
  content: {
    title: "Vite + Vanilla",

    viteLogoLabel: t({
      en: "Vite Logo",
      fr: "Logo Vite",
      es: "Logo Vite",
    }),

    count: insert(
      t({
        en: "count is {{count}}",
        fr: "le compte est {{count}}",
        es: "el recuento es {{count}}",
      })
    ),

    readTheDocs: t({
      en: "Click on the Vite logo to learn more",
      fr: "Cliquez sur le logo Vite pour en savoir plus",
      es: "Haga clic no logotipo do Vite para saber mais",
    }),
  },
} satisfies Dictionary;

export default appContent;

      As suas declarações de conteúdo podem ser definidas em qualquer lugar na sua aplicação desde que estejam incluídas no diretório contentDir (por defeito, ./src). E correspondam à extensão do ficheiro de declaração de conteúdo (por defeito, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

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

    6. Utilizar o Intlayer no seu JavaScript

      O objeto window.VanillaIntlayer fornece auxiliares de API: useIntlayer(key, locale?) devolve o conteúdo traduzido para uma determinada chave.

      src/main.js
      const { installIntlayer, useIntlayer } = window.VanillaIntlayer;

installIntlayer();

// Obter o conteúdo inicial para o idioma atual.
// Encadeie .onChange() para ser notificado sempre que o idioma mudar.
const content = useIntlayer("app").onChange((newContent) => {
  // Re-renderizar ou atualizar apenas os nós DOM afetados
  document.querySelector("h1").textContent = String(newContent.title);
  document.querySelector(".read-the-docs").textContent = String(
    newContent.readTheDocs
  );
});

// Renderização inicial
document.querySelector("h1").textContent = String(content.title);
document.querySelector(".read-the-docs").textContent = String(
  content.readTheDocs
);

      Aceda aos valores finais como strings envolvendo-os em String(), que chama o método toString() do nó e devolve o texto traduzido.

      Quando precisar do valor para um atributo HTML nativo (ex: alt, aria-label), utilize .value diretamente:

      javascript
      img.alt = content.viteLogoLabel.value;

    7. Alterar o idioma do seu conteúdo

      Opcional

      Para alterar o idioma do seu conteúdo, utilize a função setLocale exposta pelo useLocale.

      src/locale-switcher.js
      const { getLocaleName } = window.Intlayer;
const { useLocale } = window.VanillaIntlayer;

export function setupLocaleSwitcher(container) {
  const { locale, availableLocales, setLocale, subscribe } = useLocale();

  const select = document.createElement("select");
  select.setAttribute("aria-label", "Idioma");

  const render = (currentLocale) => {
    select.innerHTML = availableLocales
      .map(
        (loc) =>
          `<option value="${loc}"${loc === currentLocale ? " selected" : ""}>
            ${getLocaleName(loc)}
          </option>`
      )
      .join("");
  };

  render(locale);
  container.appendChild(select);

  select.addEventListener("change", () => setLocale(select.value));

  // Manter o dropdown sincronizado quando o idioma mudar de outro local
  return subscribe((newLocale) => render(newLocale));
}

    8. Alternar os atributos HTML de Idioma e Direção

      Opcional

      Atualize os atributos lang e dir da tag <html> para corresponderem ao idioma atual para acessibilidade e SEO.

      src/main.js
      const { getHTMLTextDir } = window.Intlayer;
const { installIntlayer, useLocale } = window.VanillaIntlayer;

installIntlayer();

useLocale({
  onLocaleChange: (locale) => {
    document.documentElement.lang = locale;
    document.documentElement.dir = getHTMLTextDir(locale);
  },
});

    9. Carregamento lento de dicionários por idioma

      Opcional

      Se pretender carregar dicionários de forma lenta por idioma, pode utilizar useDictionaryDynamic. Isto é útil se não quiser incluir todas as traduções no ficheiro inicial intlayer.js.

      src/app.js
      const { installIntlayer, useDictionaryDynamic } = window.VanillaIntlayer;

installIntlayer();

const unsubscribe = useDictionaryDynamic(
  {
    en: () => import("../.intlayer/dictionaries/en/app.mjs"),
    fr: () => import("../.intlayer/dictionaries/fr/app.mjs"),
    es: () => import("../.intlayer/dictionaries/es/app.mjs"),
  },
  "app"
).onChange((content) => {
  document.querySelector("h1").textContent = String(content.title);
});
      Nota: o useDictionaryDynamic requer que os dicionários estejam disponíveis como ficheiros ESM separados. Esta abordagem é tipicamente utilizada se tiver um servidor web a servir os dicionários.

    Configurar TypeScript

    Certifique-se de que a sua configuração TypeScript inclui os tipos autogerados.

    tsconfig.json
    {
  "compilerOptions": {
    // ...
  },
  "include": ["src", ".intlayer/**/*.ts"],
}

    Extensão VS Code

    Para melhorar a sua experiência de desenvolvimento com o Intlayer, pode instalar a Extensão oficial do Intlayer para VS Code.

    Instalar a partir do VS Code Marketplace

    Esta extensão fornece:

    • Preenchimento automático para chaves de tradução.
    • Deteção de erros em tempo real para traduções em falta.
    • Pré-visualizações inline de conteúdo traduzido.
    • Ações rápidas para criar e atualizar traduções facilmente.

    Para mais detalhes sobre como utilizar a extensão, consulte a documentação da extensão Intlayer para VS Code.

    Ir Mais Longe

    Para ir mais longe, pode implementar o editor visual ou externalizar o seu conteúdo utilizando o CMS.

    Perguntas Frequentes

    Sim. É exatamente o que este guia cobre. Você importa o bundle vanilla-intlayer diretamente no seu HTML conforme demonstrado no passo 3, inicializa-o no seu ponto de entrada e lê o conteúdo com useIntlayer. Não é necessário Vite, webpack ou qualquer pipeline de compilação obrigatório.

    Muito menos do que um catálogo de mensagens em runtime, pois a página nunca baixa um idioma que não renderiza. O conteúdo é resolvido a partir de dicionários pré-compilados, e o carregamento tardio (lazy loading) por locale mantém os outros idiomas fora do payload inicial até que o visitante alterne a língua. Comparado às opções usuais, o Intlayer reduz o tamanho do bundle e da página em até 50%. Consulte otimização de bundle, dicionários dinâmicos e o benchmark.

    Em grande parte, sim. Siga o guia de migração do i18next para transferir o conteúdo. Você também pode migrar gradualmente: o plugin sync JSON mantém seus catálogos JSON existentes como fonte de verdade e gera dicionários Intlayer a partir deles, mantendo ambas as camadas sincronizadas enquanto você migra scripts um a um.

    Sim. O plugin sync JSON mantém seus arquivos /messages/{locale}/{namespace}.json como fonte de verdade e gera dicionários Intlayer a partir deles, em ambas as direções. O plugin sync PO faz o mesmo para catálogos gettext, e os arquivos por locale permitem dividir o conteúdo por idioma em vez de agrupar todos os locales em um único arquivo.

    Não. Execute npx intlayer extract e o Intlayer lê seus arquivos fonte, extrai as strings voltadas para o usuário e escreve um arquivo .content ao lado de cada um, para que você revise um diff em vez de copiar strings para um catálogo uma a uma. Consulte o comando extract.

    Para um fluxo de trabalho totalmente automatizado, o Intlayer Compiler faz o mesmo em tempo de build em código JSX, TSX, Vue e Svelte, gerando os dicionários a cada alteração para que não haja necessidade de manter chaves manualmente. Como opera por análise estática, strings criadas exclusivamente em tempo de execução ficam fora de alcance, necessitando de algumas anotações para diferenciar texto do usuário de lógica interna da aplicação.

    Cinco ferramentas, todas opcionais:

    • Extensão VS Code: navegue de uma chave useIntlayer diretamente para o arquivo de conteúdo que a declara, extraia conteúdo de um componente e execute build, fill, test, push e pull pela paleta de comandos ou pela aba dedicada do Intlayer.
    • Servidor LSP: a mesma inteligência em qualquer editor compatível com LSP, com ir para definição, localizar referências, pré-visualizações de valores traduzidos ao passar o mouse, autocompletar e alertas para chaves não declaradas. Também resolve chamadas de i18next, react-i18next, next-intl e use-intl, facilitando a migração.
    • Servidor MCP: expõe a documentação e a CLI do Intlayer para Cursor, VS Code, Claude Desktop, Claude Code e ChatGPT, permitindo que os assistentes respondam com base na documentação atualizada e executem comandos como intlayer fill.
    • Agent Skills: habilidades focadas como intlayer-config, intlayer-cli e intlayer-content, além de uma por framework, ensinando ao agente suas regras de roteamento e tipos de nós.
    • Plugin ESLint: a regra no-raw-text identifica strings hardcoded, com regras adicionais para chaves estáticas e conteúdo não utilizado.
    Vite e Vanilla JSVite e Lit