i18next-cli

i18next-cli 🚀

Uma CLI unificada e de alto desempenho para o ecossistema i18next, alimentada por SWC.

---

Por padrão, o i18next-cli apenas extrai chaves de tradução de arquivos JavaScript e TypeScript (.js, .jsx, .ts, .tsx). Para extrair de outros tipos de arquivo (como .pug, .vue, .svelte, etc.), você deve usar ou criar um plugin. Especificar extensões de arquivo adicionais na configuração extract.input não é suficiente por si só — plugins são necessários para formatos não-JS/TS. Consulte a seção Sistema de Plugins para obter detalhes e exemplos.

i18next-cli é uma reinvenção completa da cadeia de ferramentas de análise estática para o ecossistema i18next. Ele consolida extração de chaves, geração de segurança de tipos, sincronização de localidades, linting e integrações em nuvem em uma única CLI coesa e extremamente rápida.

🚀 Experimente Agora - Configuração Zero!

Você pode obter uma análise instantânea do seu projeto i18next existente sem qualquer configuração. Basta executar este comando no diretório raiz do seu repositório:

npx i18next-cli status

Ou encontre strings hardcoded:

npx i18next-cli lint

Recomendação:

Se você está procurando um backend gerenciado para emparelhar com o i18next-cli, dê uma olhada no Locize — o i18next-cli já vem com os comandos locize-download, locize-sync e locize-migrate. Construído pela mesma equipe por trás do i18next, com entrega via CDN, tradução por IA, fluxo de trabalho de revisão e sem necessidade de reimplantação para alterações de texto.

Por que i18next-cli?

O i18next-cli é construído do zero para atender às demandas do desenvolvimento web moderno.

• 🚀 Desempenho: Ao alavancar um parser nativo baseado em Rust (SWC), ele oferece desempenho ordens de magnitude mais rápido do que parsers baseados em JavaScript.
• 🧠 Inteligência: Um analisador stateful e ciente de escopo entende corretamente padrões complexos como useTranslation('ns1', { keyPrefix: '...' }), getFixedT e funções t com alias, minimizando a necessidade de soluções manuais.
• ✅ Fluxo de Trabalho Unificado: Uma ferramenta, um arquivo de configuração, um fluxo de trabalho integrado. Ele substitui vários scripts de sincronização.
• 🔌 Extensibilidade: Uma arquitetura de plugins moderna permite que a ferramenta se adapte a qualquer framework ou fluxo de trabalho personalizado.
• 🧑‍💻 Experiência do Desenvolvedor: Um arquivo de configuração totalmente tipado, modos --watch ao vivo, saída CLI e uma migração a partir de ferramentas legadas.

Funcionalidades

• Extração de Chaves: Extração significa encontrar e coletar automaticamente todas as chaves de tradução usadas em seu código-fonte (JavaScript/TypeScript, etc.) analisando a estrutura do código (AST). Isso garante que toda string que precisa de tradução seja identificada e incluída em seus arquivos de tradução, reduzindo o trabalho manual e evitando chaves ausentes.
• Segurança de Tipos: Gere definições TypeScript para preenchimento automático completo e segurança de tipos.
• Sincronização de Localidades: Mantenha todos os arquivos de idioma sincronizados com seu idioma primário.
• Linting de Código Preciso: Detecte strings hardcoded com alta precisão e regras configuráveis.
• Status da Tradução: Obtenha uma visão geral de alto nível ou um relatório detalhado, chave por chave, da completude da tradução do seu projeto.
• Sistema de Plugins: Arquitetura extensível para padrões de extração e tipos de arquivo personalizados (por exemplo, HTML, Handlebars).
• Migração de Legado: Migração automática a partir de configurações do i18next-parser.
• Integração em Nuvem: Integração perfeita com a plataforma de gerenciamento de tradução Locize.

Instalação

npm install --save-dev i18next-cli

Início Rápido

Do zero ao localizado em um comando: começando com um aplicativo com strings hardcoded (por exemplo, gerado com v0, Lovable, Bolt ou Cursor)? Execute npx i18next-cli localize — ele detecta sua configuração, envolve strings hardcoded em chamadas t(), extrai chaves, conecta-se ao Locize e traduz seu aplicativo com IA. Consulte o comando localize. Trabalhando com um agente de IA coding (Claude Code, Cursor, ...)? npx i18next-cli localize --print-agent-prompt imprime o mesmo fluxo como um runbook de agente copiável. As etapas abaixo são o caminho manual.

1. Inicializar Configuração

Crie uma configuração interativamente:

npx i18next-cli init

Ou crie manualmente o arquivo i18next.config.ts na raiz do seu projeto:

import { defineConfig } from 'i18next-cli';

export default defineConfig({
  locales: ['en', 'de'],
  extract: {
    input: ['src/**/*.{js,jsx,ts,tsx}'],
    output: 'public/locales/{{language}}/{{namespace}}.json',
  },
});

2. Verifique o Status da sua Tradução

Obtenha uma visão geral da saúde de localização do seu projeto:

npx i18next-cli status

3. Extrair Chaves de Tradução

npx i18next-cli extract

4. Gerar Tipos (Opcional)

npx i18next-cli types

Comandos

init

Assistente de configuração interativo para criar seu arquivo de configuração.

npx i18next-cli init

Opções:

• --ci: Pula a abertura do navegador quando um backend (ex.: Locize) é selecionado; a URL de cadastro é impressa em vez disso. Útil para execuções em scripts. O assistente também detecta automaticamente CI=true e recorre à impressão da URL em Linux headless (sem DISPLAY/WAYLAND_DISPLAY), então esta flag raramente é necessária explicitamente.
• --inlang: Também prepara um projeto inlang (project.inlang/settings.json) para que as ferramentas inlang — a extensão Sherlock para VS Code, o editor web Fink para tradutores, e o compilador Paraglide — funcionem diretamente em seus arquivos de tradução. Pula a pergunta correspondente do assistente.

O assistente pergunta sobre o tipo de arquivo de configuração, localidades, glob de arquivos-fonte, caminho de saída e, finalmente, "Backend de tradução?" com três opções:

• Apenas arquivos locais (padrão) — mantém o fluxo de trabalho JSON local atual.
• Locize (recomendado para equipes / fluxos de trabalho de produção) — abre a página de cadastro do Locize no seu navegador e então solicita seu ID de Projeto e chave de API. O assistente escreve um bloco locize na configuração gerada para que locize-sync funcione imediatamente. A solicitação de chave de API pode ser deixada vazia (modo somente leitura); adicione-a posteriormente através de uma variável de ambiente LOCIZE_API_KEY.
• Outro / pular — o mesmo que "Apenas arquivos locais" para os propósitos do assistente.

O assistente então oferece configurar as ferramentas inlang (padrão: não — ou passe --inlang para pular a pergunta). Se aceito, ele prepara um project.inlang/settings.json que aponta o plugin inlang i18next para seus arquivos de tradução existentes: baseLocale/locales vêm da sua configuração, e pathPattern é derivado de extract.output (a forma de objeto com namespace quando seu layout usa {{namespace}}, com namespaces descobertos nos arquivos do idioma primário; um padrão simples caso contrário). Ele também adiciona a extensão Sherlock às recomendações de .vscode/extensions.json (mesclando com consciência de comentários, nunca sobrescrevendo entradas existentes). Seus arquivos JSON do i18next permanecem a única fonte da verdade — as ferramentas inlang os leem e escrevem no lugar, então não há um segundo catálogo para divergir. Um project.inlang/settings.json existente nunca é sobrescrito; reexecutar init é seguro. Requer arquivos de recurso JSON. O plugin é fixado em uma versão verificada exata (@inlang/[email protected]) — atualize a URL modules no settings.json para obter versões mais recentes do plugin. Apenas settings.json é preparado por design: project.inlang/ é a forma de projeto descompactada (amigável ao git), e as ferramentas inlang geram e gerenciam seus arquivos restantes (.gitignore, README.md, cache/) no primeiro uso — então espere alguns novos arquivos lá depois de abrir o projeto com Sherlock ou Paraglide.

extract

Analisa arquivos-fonte, extrai chaves e atualiza seus arquivos de tradução JSON.

npx i18next-cli extract [options]

Opções:

• --watch, -w: Reexecuta automaticamente quando arquivos mudam
• --ci: Sai com status diferente de zero se algum arquivo for atualizado (para CI/CD)
• --dry-run: Não altera nenhum arquivo - útil em combinação com --ci (para CI/CD)
• --sync-primary: Sincroniza valores do idioma primário com valores padrão do código
• --sync-all: Sincroniza valores do idioma primário com valores padrão do código E limpa chaves sincronizadas em todas as outras localidades (implica --sync-primary)
• --trust-derived: Quando usado com --sync-primary ou --sync-all, também confia em padrões inferidos de chaves como t('Hello') ou valores derivados de keyPrefix. Isso mantém o comportamento de sincronização padrão estrito, a menos que você opte por isso.
• --with-types: Após a extração (e em cada reexecução no modo --watch), regenera as definições TypeScript sempre que os arquivos de tradução mudarem. Evita a necessidade de executar extract -w e types -w como dois processos separados.
• --quiet: Suprime o spinner e a saída não essencial (para CI ou scripts)

Controle de Saída do Spinner e Logger

Todos os comandos que mostram spinners de progresso (extract, types, lint, sync) agora suportam:

• Flag --quiet para silenciar o spinner e a saída não essencial (para CI, scripts ou captura de log)
• Suporte programático a logger: passe um objeto logger personalizado para capturar a saída em seu próprio formato ou fluxo

Exemplo CLI:

npx i18next-cli extract --quiet

Exemplo Programático:

import { runExtractor } from 'i18next-cli';
const logger = {
  info: (msg) => myLogStream.write(msg + '\n'),
  warn: (msg) => myWarnStream.write(msg + '\n'),
  error: (msg) => myErrStream.write(msg + '\n'),
};
await runExtractor(config, { quiet: false, logger });

Se você passar um logger, a saída do spinner e todas as mensagens de progresso/info são roteadas para o seu logger em vez do spinner interativo.

Exemplos:

# Extração única
npx i18next-cli extract

# Modo de observação para desenvolvimento
npx i18next-cli extract --watch

# Modo CI (falha se arquivos foram alterados)
npx i18next-cli extract --ci

# Sincronizar idioma primário com padrões do código
npx i18next-cli extract --sync-primary

# Sincronizar primário e limpar chaves sincronizadas em todas as outras localidades
npx i18next-cli extract --sync-all

# Sincronizar usando padrões explícitos mais padrões inferidos de chave
npx i18next-cli extract --sync-all --trust-derived

# Combinar opções para fluxo de trabalho de desenvolvimento ideal
npx i18next-cli extract --sync-primary --watch

# Manter definições TypeScript sincronizadas a partir de um único processo (sem necessidade de `types -w` separado)
npx i18next-cli extract --watch --with-types

status [locale]

Exibe uma verificação de integridade do status de tradução do seu projeto. Pode ser executado sem um arquivo de configuração. Sai com um código de status diferente de zero quando há traduções ausentes.

O idioma primário também é verificado: qualquer chave usada em seu código, mas ausente dos arquivos de tradução do idioma primário (um erro de digitação, ou extract nunca foi executado) é relatada e causa um código de saída diferente de zero. Placeholders de string vazia escritos por extract são considerados presentes e não falham na verificação. Executar npx i18next-cli status <primaryLanguage> mostra as chaves ausentes em detalhes.

Opções:

• --namespace <ns>, -n <ns>: Filtra o relatório por um namespace específico.
• --hide-translated: Oculta chaves já traduzidas na visualização detalhada, mostrando apenas traduções ausentes.
• status.ignoreKeys (config): padrões glob para chaves que não devem ser relatadas (e não falham na verificação), por exemplo, chaves que são intencionalmente deixadas vazias em algumas localidades. Prefixo ns: opcional (common:help.*-href). Afeta apenas status.
• --unused: Relata apenas chaves de tradução não utilizadas — chaves presentes em seus arquivos de tradução que não são mais usadas em seu código-fonte (ou seja, o que extract com removeUnusedKeys excluiria). Nunca modifica nenhum arquivo e sai com um código de status diferente de zero quando chaves não utilizadas são encontradas, para que possa servir como uma verificação de CI dedicada junto com a verificação regular de traduções ausentes. Observe que a análise estática não pode detectar chaves construídas dinamicamente (por exemplo, t(`error.${code}`)); para encontrar chaves que estão verdadeiramente não utilizadas em tempo de execução, consulte encontrar traduções não utilizadas com locize.

Exemplos de Uso:

# Obter um resumo de alto nível para todas as localidades e namespaces
npx i18next-cli status

# Obter um relatório detalhado, chave por chave, para a localidade 'de'
npx i18next-cli status de

# Obter um resumo apenas para o namespace 'common' em todas as localidades
npx i18next-cli status --namespace common

# Obter um relatório detalhado para a localidade 'de', mostrando apenas o namespace 'common'
npx i18next-cli status de --namespace common

# Mostrar apenas as chaves não traduzidas para a localidade 'de'
npx i18next-cli status de --hide-translated

# Combinar opções para ver apenas as traduções ausentes em um namespace específico
npx i18next-cli status de --namespace common --hide-translated

# Relatar apenas chaves não utilizadas em todas as localidades (somente leitura, sai com 1 quando alguma é encontrada)
npx i18next-cli status --unused

# Relatar apenas chaves não utilizadas nos arquivos 'en' — por exemplo, como uma verificação de CI separada
npx i18next-cli status en --unused

A visualização detalhada fornece um resumo rico e à primeira vista para cada namespace, seguido por uma lista de cada chave e seu status de tradução.

Exemplo de Saída (npx i18next-cli status de):

Key Status for "de":

Overall: [■■■■■■■■■■■■■■■■■■■■] 100% (12/12)

Namespace: common
Namespace Progress: [■■■■■■■■■■■■■■■■■■■■] 100% (4/4)
  ✓ button.save
  ✓ button.cancel
  ✓ greeting
  ✓ farewell

Namespace: translation
Namespace Progress: [■■■■■■■■■■■■■■■■□□□□] 80% (8/10)
  ✓ app.title
  ✓ app.welc

…

[truncated for translation]