Início rápido

O modelo padrão init (ui-markdown) permite apenas a extração e tradução da interface do usuário. Os modelos ui-docusaurus, ui-starlight, ui-vitepress, ui-nextra e ui-fumadocs permitem a tradução de documentos (translate-docs); ui-vitepress também estrutura docsOutput.vitepressThemeCatalog para strings de tema VitePress, ui-nextra estrutura docs[].nextraDictionaryPath para o dicionário de tema Nextra (_meta.ts da barra lateral é coletado automaticamente), e ui-fumadocs estrutura docsOutput.fumadocsUiCatalog para substituições de UI do Fumadocs (meta.json da barra lateral é coletado automaticamente). O modelo ui-astro-website estrutura a extração da interface do usuário para aplicativos Astro simples (incluindo arquivos .astro); adicione um bloco docs[] (consulte Páginas do site Astro (analisar e substituir)) quando você também quiser translate-docs para HTML de página .astro. A referência examples/astro-website usa ambos os pipelines. Use sync quando quiser um comando que execute a extração, tradução da interface do usuário, tradução opcional de arquivos SVG e tradução de documentação de acordo com sua configuração.

Exemplos executáveis

Nove projetos e "fixtures" executáveis estão em examples/. Consulte o catálogo Exemplos (aplicativo de console, Next.js + Docusaurus, site Astro, documentos Astro Starlight, documentos VitePress, documentos Nextra, documentos Fumadocs, comparação de vários provedores, teste de estresse de markdown).

Execute um exemplo de forma independente (sem clonar o monorepo inteiro):

npx degit wsj-br/ai-i18n-tools/examples/console-app console-app
cd console-app
pnpm install
pnpm run i18n:sync    # example scripts call the locally installed CLI

Substitua console-app por qualquer nome de pasta de exemplo. Cada exemplo declara "ai-i18n-tools": "^1.7.2" e instala a CLI do npm. Os READMEs de cada exemplo incluem o mesmo trecho com o nome da pasta preenchido.

Do repositório completo ai-i18n-tools — se você clonou o repositório inteiro (não apenas uma pasta de exemplo com degit):

pnpm install          # repository root
pnpm run build        # after changing CLI source
cd examples/console-app
pnpm run i18n:sync    # preferred — uses the workspace-linked CLI
# or: ai-i18n-tools sync   # after PATH setup — see Using the CLI

A entrada do espaço de trabalho overrides (ai-i18n-tools: workspace:*) vincula exemplos de espaço de trabalho ao seu checkout local automaticamente. Os "fixtures" autônomos (multi-provider, test-markdown) não são pacotes de espaço de trabalho — de sua pasta, use node ../../bin/ai-i18n-tools.mjs …. Para executar a CLI a partir da raiz do repositório (documentos/i18n deste pacote), use pnpm i18n:sync ou node bin/ai-i18n-tools.mjs … — consulte Instalação — Monorepo clonado e o Guia de Desenvolvimento.

Provedor e chave de API (obrigatório para tradução)

Todo comando que chama um LLM — translate-ui, translate-docs, translate-json, translate-svg e sync — precisa de ambos:

1. Pelo menos um provedor em ai-i18n-tools.config.json: um bloco providers.<name> com translationModels, e uma chave provider de nível superior quando mais de um provedor é configurado. init estrutura um bloco de provedor padrão (openrouter, a menos que você passe -P <provider>); altere predefinições, adicione provedores ou ajuste listas de modelos — consulte Provedores e modelos LLM.
2. A chave de API correspondente em seu ambiente ou um arquivo .env na raiz do projeto. Cada predefinição integrada lê uma variável de ambiente nomeada da tabela de predefinições (por exemplo, OPENROUTER_API_KEY para o padrão, ou ANTHROPIC_API_KEY quando você estrutura com -P anthropic); Ollama é a exceção — ele usa um endpoint local e não precisa de chave. Consulte Instalação — defina sua chave de API do provedor.

extract, status e outros comandos que não chamam o LLM não precisam de um provedor ou chave de API.

Comandos principais da CLI

Execute a partir da raiz do seu projeto após instalar ai-i18n-tools e configurar seu shell para o comando básico. Os exemplos abaixo usam ai-i18n-tools diretamente.

# Set the API key for your active provider (see preset table; skip for local Ollama)
# Default init uses openrouter:
export OPENROUTER_API_KEY=sk-or-v1-your-key-here
# Or scaffold another preset at init, e.g. anthropic:
# export ANTHROPIC_API_KEY=sk-ant-your-key-here

# UI strings (default template enables extract + translate-ui)
ai-i18n-tools init [-P <provider>]    # default: openrouter
ai-i18n-tools init -P anthropic
ai-i18n-tools extract
ai-i18n-tools translate-ui

# Documents (Docusaurus-oriented template)
ai-i18n-tools init -t ui-docusaurus [-P <provider>]
ai-i18n-tools init -t ui-docusaurus -P openai
# Astro Starlight docs: ai-i18n-tools init -t ui-starlight [-P <provider>]
# VitePress docs: ai-i18n-tools init -t ui-vitepress [-P <provider>]
# Nextra docs: ai-i18n-tools init -t ui-nextra [-P <provider>]
# Fumadocs docs: ai-i18n-tools init -t ui-fumadocs [-P <provider>]
# Plain Astro website UI: ai-i18n-tools init -t ui-astro-website [-P <provider>]
ai-i18n-tools translate-docs

# JSON (no t() in source)
ai-i18n-tools init -t ui-json-bundles [-P <provider>]
ai-i18n-tools translate-json

# Combined: extract UI strings, then translate UI + SVG + docs + json[] (per config features)
ai-i18n-tools sync

# Translation status (UI strings per locale; markdown per file × locale in chunked tables)
ai-i18n-tools status
# ai-i18n-tools status --max-columns 12   # wider tables, fewer chunks

Scripts recomendados do package.json

Com o pacote instalado localmente, os scripts package.json resolvem ai-i18n-tools de node_modules/.bin sem configuração extra do shell. Para shells interativos, configure o PATH primeiro — consulte Usando a CLI.

Prefira sync para qualquer tarefa que antes era “execute translate-ui, depois translate-svg, depois translate-docs, depois translate-json”: ai-i18n-tools sync executa extract (quando habilitado), translate-ui, opcional translate-svg, translate-docs e opcional translate-json — na ordem correta e com flags compartilhadas — de acordo com sua configuração. Encadear essas etapas manualmente é propenso a erros (ordem, extração, flags de localidade). Use i18n:translate:ui, i18n:translate:svg, i18n:translate:docs e i18n:translate:json apenas quando precisar de uma etapa única isoladamente.

{
  "i18n:extract": "ai-i18n-tools extract",
  "i18n:sync": "ai-i18n-tools sync",
  "i18n:translate:ui": "ai-i18n-tools translate-ui",
  "i18n:translate:svg": "ai-i18n-tools translate-svg",
  "i18n:translate:docs": "ai-i18n-tools translate-docs",
  "i18n:translate:json": "ai-i18n-tools translate-json",
  "i18n:status": "ai-i18n-tools status",
  "i18n:statistics": "ai-i18n-tools statistics",
  "i18n:dashboard": "ai-i18n-tools dashboard",
  "i18n:cleanup": "ai-i18n-tools cleanup"
}

Dica: Passe -L <code> ou defina AI_I18N_LANG se você quiser a saída da CLI e o painel em outro idioma — consulte Idioma da IU da ferramenta.

Sincronização combinada

Habilite todos os recursos em uma única configuração para executar strings de interface do usuário e documentos juntos:

Exemplo de configuração combinada de UI + docs

{
  "sourceLocale": "en-GB",
  "targetLocales": ["de", "fr", "es", "pt-BR", "ja", "ko", "zh-Hans"],
  "features": {
    "translateUIStrings": true,
    "translateDocs": true,
    "translateSVG": false
  },
  "glossary": {
    "uiGlossary": "src/locales/strings.json",
    "userGlossary": "glossary-user.csv"
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "src/locales/strings.json",
    "flatOutputDir": "src/locales/"
  },
  "cacheDir": ".translation-cache",
  "docs": [
    {
      "contentPaths": ["docs/"],
      "outputDir": "i18n/",
      "docsOutput": { "style": "flat" }
    }
  ]
}

glossary.uiGlossary direciona a tradução de documentos ao mesmo catálogo strings.json da interface, mantendo a terminologia consistente; glossary.userGlossary adiciona substituições CSV para termos do produto.

Execute ai-i18n-tools sync para executar um pipeline: quando features.translateUIStrings estiver habilitado, extraia e depois traduza strings da UI; opcionalmente traduza SVG (bloco features.translateSVG + svg); traduza a documentação (docs[] conforme configurado); então opcionalmente traduza-json (features.translateJson + json[]). Pule partes com --no-ui, --no-svg, --no-docs ou --no-json. As etapas de documentos e json[] aceitam --dry-run, -p / --path, --force e --force-update (sinalizadores somente de documentos são ignorados quando --no-docs; JSON usa os mesmos sinalizadores de cache quando --no-json não está definido).

Use docs[].targetLocales em um bloco para traduzir os arquivos desse bloco para um subconjunto menor do que a interface (as localidades efetivas da documentação são a união entre blocos):

{
  "targetLocales": ["de", "fr", "es", "pt-BR", "ja", "ko", "zh-Hans"],
  "docs": [
    {
      "contentPaths": ["docs/"],
      "outputDir": "i18n/",
      "targetLocales": ["de", "fr", "es"]
    }
  ]
}

Configuração de documentação mista (docsOutput.style = "docusaurus" + "flat")

Você pode combinar múltiplos pipelines de documentação na mesma configuração adicionando mais de uma entrada em docs. Essa é uma configuração comum quando um projeto possui um site Docusaurus (docsOutput.style = "docusaurus") além de arquivos markdown no nível raiz (por exemplo, um README de repositório com docsOutput.style = "flat") que devem ser traduzidos com nomes de arquivo sufixados pela localidade.

Exemplo de configuração mista Docusaurus + README plana

{
  "sourceLocale": "en-GB",
  "targetLocales": ["ar", "es", "fr", "de", "pt-BR"],
  "features": {
    "translateUIStrings": true,
    "translateDocs": true
  },
  "ui": {
    "sourceRoots": ["src/"],
    "stringsJson": "locales/strings.json",
    "flatOutputDir": "public/locales/"
  },
  "cacheDir": ".translation-cache",
  "docs": [
    {
      "description": "Docusaurus site content (markdown)",
      "contentPaths": ["docs-site/docs/"],
      "outputDir": "docs-site/i18n",
      "docusaurusCatalogDir": "docs-site/i18n/en",
      "addFrontmatter": true,
      "docsOutput": {
        "style": "docusaurus",
        "docsRoot": "docs-site/docs"
      }
    },
    {
      "description": "Root README with docsOutput.style flat",
      "contentPaths": ["README.md"],
      "outputDir": "translated-docs",
      "addFrontmatter": false,
      "docsOutput": {
        "style": "flat",
        "postProcessing": {
          "languageListBlock": {
            "start": "<small id=\"lang-list\">",
            "end": "</small>",
            "separator": " · ",
            "label": "local"
          }
        }
      }
    }
  ]
}

Como isso é executado com ai-i18n-tools sync:

• Strings de interface são extraídas/traduzidas de src/ para public/locales/.
• O primeiro bloco de documentação traduz markdown de docs-site/docs/ para docs-site/i18n/<locale>/docusaurus-plugin-content-docs/current/ (páginas de documentação localizadas).
• Com docs[].docusaurusCatalogDir definido e features.translateDocs habilitado, esse mesmo bloco também traduz o JSON do shell do Docusaurus em docs-site/i18n/en/ para cada pasta de localidade de destino — navbar, rodapé e catálogos de tema/plugin, não o conteúdo do corpo MDX.
• O segundo bloco de documentação traduz README.md para arquivos com sufixo de localidade em translated-docs/ (docsOutput.style = "flat").
• Todos os blocos de docs compartilham cacheDir, portanto segmentos inalterados são reutilizados entre execuções para reduzir chamadas à API e custos.