Intlayer Compiler | Extração Automática de Conteúdo para i18n

O que é o Intlayer Compiler?

O Intlayer Compiler é uma ferramenta poderosa projetada para automatizar o processo de internacionalização (i18n) em suas aplicações. Ele escaneia seu código-fonte (JSX, TSX, Vue, Svelte) em busca de declarações de conteúdo, extrai-as e gera automaticamente os arquivos de dicionário necessários. Isso permite que você mantenha seu conteúdo localizado junto aos seus componentes, enquanto o Intlayer gerencia e sincroniza seus dicionários.

Por que Usar o Intlayer Compiler?

• Automação: Elimina a cópia manual de conteúdo para dicionários.

• Speed: Extração de conteúdo otimizada garantindo que seu processo de build permaneça rápido.

• Developer Experience: Mantenha as declarações de conteúdo onde são usadas, melhorando a manutenibilidade.

• Automação: Elimina a cópia manual e colagem de conteúdo nos dicionários.
• Velocidade: Extração de conteúdo otimizada garantindo que seu processo de build permaneça rápido.
• Experiência do Desenvolvedor: Mantenha as declarações de conteúdo exatamente onde são usadas, melhorando a manutenção.
• Atualizações em Tempo Real: Suporta Hot Module Replacement (HMR) para feedback instantâneo durante o desenvolvimento.

Veja o post do blog Compiler vs. Declarative i18n para uma comparação mais aprofundada.

Por que não usar o Intlayer Compiler?

Embora o compilador ofereça uma excelente experiência "funciona automaticamente", ele também introduz algumas compensações das quais você deve estar ciente:

• Ambiguidade heurística: O compilador deve adivinhar o que é conteúdo voltado para o usuário versus a lógica da aplicação (por exemplo, className="active", códigos de status, IDs de produtos). Em bases de código complexas, isso pode levar a falsos positivos ou strings perdidas que exigem anotações manuais e exceções.

• Extração apenas estática: A extração baseada em compilador depende de análise estática. Strings que existem apenas em tempo de execução (códigos de erro de API, campos CMS, etc.) não podem ser descobertas ou traduzidas pelo compilador sozinho, então você ainda precisa de uma estratégia i18n de tempo de execução complementar.

• Extração estática apenas: A extração baseada em compilador depende de análise estática. Strings que existem apenas em tempo de execução (códigos de erro de API, campos de CMS, etc.) não podem ser descobertos ou traduzidos pelo compilador sozinho, portanto você ainda precisa de uma estratégia de i18n em tempo de execução complementar.

Para uma comparação arquitetural mais profunda, veja o post do blog Compiler vs. Declarative i18n.

Como alternativa, para automatizar seu processo i18n mantendo controle total sobre seu conteúdo, o Intlayer também fornece um comando de auto-extração intlayer extract (consulte a documentação CLI), ou o comando Intlayer: extract content to Dictionary da extensão Intlayer VS Code (consulte a documentação da extensão VS Code).

Uso

A forma mais rápida de integrar o compiler é através da configuração interativa: execute npx intlayer init --interactive e selecione Compiler. No Vite não há nada para configurar — o compiler é conectado diretamente através do plugin principal intlayer() (é ativado automaticamente uma vez que compiler.enabled está definido e um caminho compiler.output é configurado). No Next.js o comando gera o babel.config.js mostrado abaixo. O intlayer init não-interativo deixa a configuração do compiler intocada.

npm install vite-intlayer

import { defineConfig } from "vite";
import { intlayer } from "vite-intlayer";

export default defineConfig({
  plugins: [
    intlayer({
      proxy: {
        ignore: (req) => req.url?.startsWith("/api"),
      },
    }),
  ],
});

# Para Vue
npm install @intlayer/vue-compiler

# Para Svelte
npm install @intlayer/svelte-compiler

npm install @intlayer/babel

const {
  intlayerExtractBabelPlugin,
  intlayerOptimizeBabelPlugin,
  getExtractPluginOptions,
  getOptimizePluginOptions,
} = require("@intlayer/babel");

module.exports = {
  presets: ["next/babel"],
  plugins: [
    // Extract content from components into dictionaries
    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
    // Optimize imports by replacing useIntlayer with direct dictionary imports
    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
  ],
};

Configuração personalizada

Para personalizar o comportamento do compilador, você pode atualizar o arquivo intlayer.config.ts na raiz do seu projeto.

import { type IntlayerConfig, Locales } from "intlayer";

const config: IntlayerConfig = {
  compiler: {
    /**
     * Indica se o compilador deve ser habilitado.
     * Defina como 'build-only' para ignorar o compilador durante o desenvolvimento e acelerar os tempos de inicialização.
     */
    enabled: true,

    /**
     * Define o caminho dos arquivos de saída. Substitui `outputDir`.
     *
     * - Os caminhos `./` são resolvidos em relação ao diretório do componente.
     * - Os caminhos `/` são resolvidos em relação à raiz do projeto (`baseDir`).
     *
     * - A inserção da variável `{{locale}}` no caminho ativará a geração de dicionários separados por idioma.
     *
     * Exemplo:
     * ```ts
     * {
     *   // Cria arquivos .content.ts multilíngues próximos ao componente
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Equivalente usando uma string template
     * }
     * ```
     *
     * ```ts
     * {
     *   // Cria arquivos JSON centralizados por idioma na raiz do projeto
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalente usando uma string template
     * }
     * ```
     *
     * Lista de variáveis:
     *   - `fileName`: O nome do arquivo.
     *   - `key`: A chave do conteúdo.
     *   - `locale`: O idioma do conteúdo.
     *   - `extension`: A extensão do arquivo.
     *   - `componentFileName`: O nome do arquivo do componente.
     *   - `componentExtension`: A extensão do arquivo do componente.
     *   - `format`: O formato do dicionário.
     *   - `componentFormat`: O formato do dicionário do componente.
     *   - `componentDirPath`: O caminho do diretório do componente.
     */
    output: ({ fileName, extension }) => `./${fileName}${extension}`,

    /**
     * Se deve guardar as componentes após serem transformadas.
     *
     * - Se `true`, o compilador reescreverá o arquivo do componente no disco. Portanto, a transformação será permanente, e o compilador pulará a transformação para o próximo processo. Dessa forma, o compilador pode transformar o app, e então pode ser removido.
     *
     * - Se `false`, o compilador injetará a chamada da função `useIntlayer()` no código apenas na saída da build, e manterá a base de código original intacta. A transformação será feita apenas em memória.
     */
    saveComponents: false,

    /**
     * Inserir apenas o conteúdo no arquivo gerado. Útil para saídas i18next ou ICU MessageFormat JSON por idioma.
     *
     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`
     */
    noMetadata: false,

    /**
     * Prefixo da chave do dicionário
     */
    dictionaryKeyPrefix: "", // Adicione um prefixo opcional para as chaves de dicionário extraídas
  },
};

export default config;

Referência de configuração do compilador

As seguintes propriedades podem ser configuradas no bloco compiler do seu arquivo intlayer.config.ts:

• enabled:

  • Tipo: boolean | 'build-only'
  • Padrão: true
  • Descrição: Indica se o compilador deve ser habilitado.

• dictionaryKeyPrefix:

  • Tipo: string
  • Padrão: ''
  • Descrição: Prefixo para as chaves de dicionário extraídas.

• transformPattern:

  • Tipo: string | string[]
  • Padrão: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Descrição: (Obsoleto: use build.traversePattern em seu lugar) Padrões para percorrer o código a ser otimizado.

• excludePattern:

  • Tipo: string | string[]
  • Padrão: ['**/node_modules/**']
  • Descrição: (Obsoleto: use build.traversePattern em seu lugar) Padrões para excluir da otimização.

• output:

  • Tipo: FilePathPattern
  • Padrão: ({ key }) => 'compiler/${key}.content.json'
  • Descrição: Define o caminho dos arquivos de saída. Substitui outputDir. Manipula variáveis dinâmicas como {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}. Pode ser definido como uma string usando o formato 'my/{{var}}/path' ou como uma função.
  • Nota: ./**/* Os caminhos são resolvidos relativamente ao componente. /**/* os caminhos são resolvidos relativamente ao baseDir do Intlayer.
  • Nota: Se o idioma for definido no caminho, os dicionários serão gerados por idioma.
  • Exemplo: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Indica se os metadados devem ser salvos no arquivo. Se verdadeiro, o compilador não salvará os metadados dos dicionários (chave, wrapper de conteúdo). Útil para saídas JSON i18next ou ICU MessageFormat por localidade.
  • Nota: Útil se usado com o plugin loadJSON.
  • Exemplo: Se true: json { "key": "value" } Se false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Tipo: boolean
  • Padrão: false
  • Descrição: Indica se os componentes devem ser salvos após serem transformados.
    • Se true, o compilador reescreverá o arquivo do componente no disco. A transformação será permanente, e o compilador poderá ser removido.
    • Se false, o compilador injetará a chamada da função useIntlayer() no código apenas na saída da build, mantendo a base de código original intacta. A transformação será feita apenas em memória.

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

Extração

Intlayer fornece uma ferramenta CLI para extrair conteúdo do seu código. Você pode usar o comando intlayer extract para extrair o conteúdo do seu código.

npx intlayer extract

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