Autor:
    Aymeric PINEAU
    Criação:2025-08-23Última atualização:2026-08-30

    Documentação do Intlayer

    Bem-vindo à documentação oficial do Intlayer! Aqui, você encontrará tudo o que precisa para integrar, configurar e dominar o Intlayer para todas as suas necessidades de internacionalização (i18n), quer esteja trabalhando com Next.js, React, Vite, Express ou outro ambiente JavaScript.

    Introdução

    O que é o Intlayer?

    Intlayer é uma biblioteca de internacionalização concebida especificamente para desenvolvedores JavaScript. Permite a declaração do seu conteúdo em qualquer lugar do seu código. Converte a declaração de conteúdo multilingue em dicionários estruturados para se integrar facilmente no seu código. Utilizando TypeScript, o Intlayer torna o seu desenvolvimento mais robusto e eficiente.

    O Intlayer também fornece um editor visual opcional que permite editar e gerenciar facilmente o seu conteúdo. Este editor é particularmente útil para desenvolvedores que preferem uma interface visual para gestão de conteúdo, ou para equipes que geram conteúdo sem se preocuparem com o código.

    Exemplo de utilização

    bash
    .
└── Components
    └── MyComponent
        ├── index.content.ts
        └── index.tsx
    src/components/MyComponent/index.content.ts
    import { t, type Dictionary } from "intlayer";

const componentContent = {
  key: "component-key",
  content: {
    myTranslatedContent: t({
      en: "Hello World",
      es: "Hola Mundo",
      fr: "Bonjour le monde",
      pt: "Olá Mundo",
    }),
  },
} satisfies Dictionary;

export default componentContent;
    src/components/MyComponent/index.tsx
    import type { FC } from "react";
import { useIntlayer } from "react-intlayer";

export const MyComponent: FC = () => {
  const { myTranslatedContent } = useIntlayer("component-key");

  return <span>{myTranslatedContent}</span>;
};

    Por que o Intlayer em vez das alternativas?

    Em comparação com soluções principais como next-intl ou i18next, o Intlayer é uma solução que vem com otimizações integradas, tais como:

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

    Manter o conteúdo próximo aos componentes da sua aplicação facilita a manutenção para aplicações de grande escala. Você pode duplicar ou apagar uma única pasta de funcionalidade sem o fardo mental de rever toda a sua base de código de conteúdos. Além disso, o Intlayer é totalmente tipado (fully typed) para garantir a exatidão dos seus conteúdos.

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

    Utilize a automatização para traduzir no seu pipeline CI/CD usando o LLM da sua preferência pelo custo do seu fornecedor 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 ficheiros JSON massivos a componentes pode levar a problemas de desempenho e reatividade. O Intlayer otimiza o carregamento do seu conteúdo em tempo de compilação (build time).

    Muito mais do que apenas uma solução de i18n, o Intlayer fornece um editor visual auto-hospedado e um CMS completo para o ajudar a gerenciar o seu conteúdo multilingue em tempo real, tornando a colaboração com tradutores, copywriters e outros membros da equipe perfeitamente fluida. O conteúdo pode ser armazenado local e/ou remotamente.

    Principais características

    O Intlayer oferece uma variedade de funcionalidades adaptadas para satisfazer as necessidades do desenvolvimento web moderno. Abaixo estão as principais funcionalidades, com links para a documentação detalhada de cada uma:

    • Suporte de internacionalização: Melhore o alcance global da sua aplicação com suporte integrado para internacionalização.
    • Editor Visual: Melhore o seu fluxo de trabalho de desenvolvimento com plugins de editor concebidos para o Intlayer. Consulte o Guia do Editor Visual.
    • Flexibilidade de configuração: Personalize a sua configuração com opções de configuração abrangentes detalhadas no Guia de Configuração.
    • Ferramentas CLI avançadas: Gira os seus projetos de forma eficiente utilizando a interface de linha de comandos do Intlayer. Explore as capacidades na Documentação de Ferramentas CLI.

    Conceitos principais

    Dicionário

    Organize o seu conteúdo multilingue perto do seu código para manter tudo consistente e fácil de manter.

    • Começar
      Aprenda os conceitos básicos de como declarar o seu conteúdo no Intlayer.

    • Tradução
      Compreenda como as traduções são geradas, armazenadas e utilizadas na sua aplicação.

    • Enumeração
      Gira facilmente conjuntos de dados repetidos ou fixos em vários idiomas.

    • Condição
      Aprenda a utilizar a lógica condicional no Intlayer para criar conteúdo dinâmico.

    • Inserção Descubra como inserir valores numa string utilizando espaços reservados (placeholders).

    • Busca por Função
      Veja como buscar conteúdo dinamicamente com lógica personalizada para corresponder ao fluxo de trabalho do seu projeto.

    • Markdown
      Aprenda a utilizar o Markdown no Intlayer para criar conteúdo rico.

    • Incorporação de Ficheiros
      Descubra como incorporar ficheiros externos no Intlayer para utilizá-los no editor de conteúdo.

    • Aninhamento
      Compreenda como aninhar conteúdo no Intlayer para criar estruturas complexas.

    Ambientes e Integrações

    Construímos o Intlayer a pensar na flexibilidade, oferecendo integração perfeita nos frameworks e ferramentas de build mais populares:

    Cada guia de integração inclui as melhores práticas para utilizar as funcionalidades do Intlayer, como renderização do lado do servidor (SSR), roteamento dinâmico ou renderização no lado do cliente, para que possa manter uma aplicação rápida, amiga do SEO e altamente escalável.

    Contribuição e Feedback

    Valorizamos o poder do código aberto e do desenvolvimento focado na comunidade. Se gostaria de propor melhorias, adicionar um novo guia ou corrigir quaisquer problemas na nossa documentação, sinta-se à vontade para submeter um Pull Request ou abrir uma issue no nosso repositório GitHub.

    Pronto para traduzir a sua aplicação de forma mais rápida e eficiente? Mergulhe na nossa documentação para começar a utilizar o Intlayer hoje mesmo. Experiencie uma abordagem robusta e simplificada à internacionalização que mantém o seu conteúdo organizado e a sua equipe mais produtiva.

    Perguntas Frequentes

    O Intlayer é uma biblioteca de internacionalização (i18n) para aplicações JavaScript e TypeScript. Você declara o conteúdo de um componente ao lado do próprio componente em um arquivo .content.ts, o Intlayer compila essas declarações em dicionários tipados durante o build, e seus componentes os consomem por meio de um hook como useIntlayer. Ele abrange traduções, regras de plural, gênero, Markdown, roteamento ciente de locale, metadados de SEO, tradução assistida por IA e um editor visual para colaboradores não desenvolvedores.

    Muito menos do que uma configuração baseada em namespaces, porque uma página nunca baixa um catálogo que não renderiza. O markup renderizado no servidor resolve seu conteúdo no próprio servidor, e o compilador em tempo de build substitui as chamadas useIntlayer pelas entradas exatas que o componente utiliza, descartando chaves e idiomas não utilizados. Os dicionários dinâmicos dividem o restante por locale. Comparado às alternativas habituais, o Intlayer reduz o tamanho do bundle e da página em até 50%. Consulte otimização de bundle e o benchmark.

    Sim, e existem dois caminhos. Você pode migrar o conteúdo progressivamente com o guia de migração do i18next ou o guia de migração do next-intl. Ou você pode manter sua API atual integralmente: os adaptadores de compatibilidade (compat adapters) expõem exatamente a mesma interface de i18next, react-i18next, next-intl, next-i18next, react-intl, use-intl, vue-i18n e Lingui, porém alimentados pelos dicionários do Intlayer, permitindo que apenas os imports mudem enquanto o código dos componentes permanece idêntico.

    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.
    Por que Intlayer?Como o Intlayer funciona