Skip to content

Referência de configuração ​

sourceLocale ​

Código BCP-47 para o idioma de origem (por exemplo, "en-GB", "pt-BR" ou "ja"). Qualquer idioma é válido. O inglês aparece nos exemplos porque muitos projetos começam por ele. Nenhum arquivo de tradução é gerado para esta localidade — a própria string da chave é o texto de origem.

Deve coincidir com o SOURCE_LOCALE exportado do seu arquivo de configuração de i18n em tempo de execução (src/i18n.ts / src/i18n.js).


targetLocales ​

Matriz de códigos de locale BCP-47 para os quais traduzir (por exemplo, ["de", "fr", "es", "pt-BR"]).

targetLocales é a lista principal de locales para tradução da interface e a lista padrão de locales para blocos de documentação. Use generate-ui-languages para gerar o manifesto ui-languages.json a partir de sourceLocale + targetLocales.


uiLanguage (opcional) ​

Código BCP-47 para o idioma da interface do usuário da ferramenta (ajuda da CLI, logs/resumos e o Painel de Tradução). É independente de sourceLocale / targetLocales e é substituído pelo sinalizador -L / --ui-lang e pela variável de ambiente AI_I18N_LANG. Valores desconhecidos são degradados para o idioma de origem (en-GB) — não há validação estrita. Consulte Idioma da interface do usuário da ferramenta.


languagesManifestPath (opcional) ​

String opcional no nível raiz. O seletor de idioma da documentação lê este caminho. Quando omitido, o padrão é o manifesto do primeiro bloco de UI: o languagesManifestPath desse bloco, ou {flatOutputDir}/ui-languages.json. Cada bloco de UI pode definir seu próprio languagesManifestPath; o bloco 0 usa este caminho raiz quando o bloco omite o seu próprio.

Use isso quando:

  • O manifesto deve residir fora de ui.flatOutputDir (por exemplo, ao lado dos auxiliares do aplicativo em src/i18n/).
  • Você deseja que o pós-processamento do seletor de idioma (languageListBlock) construa rótulos de localidade a partir do manifesto do projeto, em vez de apenas o catálogo mestre empacotado.

includeUiLanguageEnglishNames não lê este arquivo — ele usa o catálogo mestre empacotado (veja ui.uiExtractor abaixo).

Legado: uiLanguagesPath de nível raiz ainda é aceito ao carregar um arquivo de configuração e é reescrito automaticamente para languagesManifestPath.


concurrency (opcional) ​

Número máximo de locais de destino traduzidos simultaneamente (translate-ui, translate-docs, translate-svg e as etapas correspondentes dentro de sync). Se omitido, a CLI usa 4 para tradução de UI e 3 para tradução de documentação (padrões incorporados). Substitua por execução com -j / --concurrency.


batchConcurrency (opcional) ​

translate-docs, translate-svg e translate-json (e as etapas correspondentes dentro de sync): número máximo de solicitações de lote LLM paralelas por arquivo (cada lote pode conter muitos segmentos). O padrão é 4 quando omitido. Não se aplica a translate-ui — use uiBatchConcurrency em vez disso. Substitua por -b / --batch-concurrency.


uiBatchConcurrency (opcional) ​

translate-ui, sync-ui e a etapa de UI de sync: máximo de solicitações em lote paralelas de LLM dentro de um único local (blocos de string simples de 50, depois grupos plurais). Padrão 2 quando omitido. Independente de concurrency (locais de destino paralelos) e batchConcurrency (docs/JSON/SVG). Sem flag de CLI; defina-o na configuração ou passe uiBatchConcurrency para runTranslateUI programático.

Exemplo:

json
{
  "uiBatchConcurrency": 2
}

Com a concorrência de localidade padrão de 4, isso significa até 8 chamadas de API de UI em andamento. Aumente esse valor ao traduzir uma localidade grande (-l de); mantenha-o baixo se o provedor limitar a taxa.


fileConcurrency (opcional) ​

Número máximo de arquivos processados simultaneamente dentro de um único idioma durante translate-docs e sync. Quando definido como um valor maior que 1, os arquivos dentro do mesmo idioma são processados em paralelo usando um semáforo para controlar o uso de memória. O valor padrão é 1 (processamento sequencial) quando omitido. Valores mais altos podem melhorar significativamente o desempenho em operações limitadas por E/S, especialmente quando todos os segmentos já estão em cache (sem chamadas à API necessárias).

Exemplo:

json
{
  "fileConcurrency": 4
}

Caso de uso: Defina isso como 2-4 ao executar sync --force-update com 100% de acertos no cache para reduzir o tempo total de processamento. A melhoria é mais perceptível com muitos arquivos pequenos.


batchSize / maxBatchChars (opcional) ​

Agrupamento de segmentos para translate-docs, translate-svg e translate-json: quantos segmentos por solicitação de API e um limite de caracteres. Padrões: 20 segmentos, 4096 caracteres (quando omitido).


requestTimeout / requestTimeoutMs (opcional) ​

Tempo máximo de espera para cada solicitação LLM, para cada provedor. requestTimeout são segundos inteiros; requestTimeoutMs são milissegundos. Padrão: 120 segundos quando ambos são omitidos. Defina apenas um dos dois. Um provedor que define qualquer um dos campos usa esse valor, apenas para esse provedor.


provider e providers ​

provider (nível superior, opcional) seleciona a chave do provedor ativo de providers. É opcional quando exatamente um provedor é configurado; obrigatório quando mais de um é configurado.

providers (nível superior) mapeia uma chave de provedor para seu bloco. As chaves internas (consulte a tabela de predefinições abaixo) precisam apenas de translationModels; qualquer outra chave define um endpoint personalizado compatível com OpenAI e requer baseUrl (mais apiKeyEnv, a menos que o endpoint não precise de chave).

Cada bloco providers.<name> aceita:

  • translationModels Lista ordenada preferencial de IDs de modelo (IDs upstream simples, sem prefixo provider/; IDs do OpenRouter mantêm sua forma nativa vendor/model). O primeiro é tentado primeiro; entradas posteriores são alternativas em caso de erro. Esta é a cadeia padrão global para cada pipeline quando nenhum nível mais específico se aplica.
  • uiModels (opcional) Lista de modelos ordenada apenas para UI para translate-ui, geração de plural (Etapa 0 e Passagem B) e proofread-ui. Tentada após qualquer entrada localeModels correspondente para o local de destino, antes de translationModels.
  • localeModels (opcional) Substituições por local para todos os pipelines de tradução. Array de objetos { "locale": "<BCP-47>", "models": ["…"] }. As tags de local são correspondidas sem distinção entre maiúsculas e minúsculas (pt-br = pt-BR). A lista de cada local é tentada primeiro apenas para esse local, depois os níveis específicos do pipeline (uiModels para UI) e translationModels. Chaves de local normalizadas duplicadas são rejeitadas no carregamento da configuração.
  • baseUrl URL base compatível com OpenAI. Substitui a URL base predefinida; necessária para um provedor não predefinido.
  • apiKeyEnv Variável de ambiente que contém a chave da API. Substitui a variável de ambiente predefinida.
  • headers Cabeçalhos HTTP extras enviados com cada solicitação para este provedor.
  • maxTokens Máximo de tokens de conclusão por solicitação. Padrão: 8192.
  • temperature Temperatura de amostragem. Padrão: 0.2.
  • requestTimeout Tempo máximo em segundos para aguardar cada solicitação a este provedor. Substitui o requestTimeout / requestTimeoutMs de nível superior. Quando nem este provedor nem a configuração de nível superior definem um tempo limite, o padrão é 120 segundos. Defina apenas um de requestTimeout e requestTimeoutMs no mesmo objeto.
  • requestTimeoutMs Tempo máximo em milissegundos para aguardar cada solicitação a este provedor. Substitui o requestTimeout / requestTimeoutMs de nível superior. Quando nem este provedor nem a configuração de nível superior definem um tempo limite, o padrão é 120000 (120 segundos). Defina apenas um de requestTimeout e requestTimeoutMs no mesmo objeto.
  • pricing (opcional) USD por 1M de tokens para todo o provedor: { "inputPerMTokens": 0.15, "outputPerMTokens": 0.6 }. Quando uma chamada faturada não tem usage.cost relatado pelo provedor (a maioria dos provedores, exceto OpenRouter e Cheaper Inference), esta taxa é aplicada aos tokens de entrada e saída dessa chamada. O valor é incluído no resumo da tradução e armazenado na linha api_calls.

A fonte de custo é resolvida nesta ordem:

  1. uma entrada modelPricing correspondente (substitui o padrão deste provedor);
  2. um custo relatado pelo provedor (nunca substituído);
  3. esta taxa pricing;
  4. o preço de tabela do models.dev para esse ID de modelo (USD de entrada e saída por 1M de tokens).

Linhas que foram armazenadas sem custo ainda podem ser estimadas posteriormente por usage e Uso e custos. Se nenhuma dessas fontes se aplicar, o custo permanece desconhecido (—), nunca $0.00.

  • modelPricing (opcional) USD por 1M de tokens por modelo: { "<model-id>": { "inputPerMTokens": 2.5, "outputPerMTokens": 10 } }. Substitui pricing para esse ID de modelo. Aplicado no momento da chamada quando o provedor omitiu usage.cost, e armazenado com a chamada.
  • zeroDataRetention (opcional, apenas providers.cheaperinference) Quando true, as solicitações de chat enviam "zdr": true e list-models, check-models e suggest-models carregam GET /v1/models?zdr=true. Omitido significa desativado. Consulte Retenção zero de dados.

Presets de provedores integrados (chave — URL base — variável de ambiente da chave de API):

ProvedorURL baseVariável de ambiente da chave de API
alibabahttps://dashscope-intl.aliyuncs.com/compatible-mode/v1ALIBABA_API_KEY
anthropichttps://api.anthropic.com/v1ANTHROPIC_API_KEY
apikeyfanhttps://api.apikey.fan/v1APIKEYFAN_API_KEY
cerebrashttps://api.cerebras.ai/v1CEREBRAS_API_KEY
cheaperinferencehttps://api.cheaperinference.com/v1CHEAPERINFERENCE_API_KEY
deepseekhttps://api.deepseek.comDEEPSEEK_API_KEY
geminihttps://generativelanguage.googleapis.com/v1beta/openaiGOOGLE_API_KEY
groqhttps://api.groq.com/openai/v1GROQ_API_KEY
mistralhttps://api.mistral.ai/v1MISTRAL_API_KEY
nvidiahttps://integrate.api.nvidia.com/v1NVIDIA_API_KEY
ollamahttp://localhost:11434/v1(nenhum)
openaihttps://api.openai.com/v1OPENAI_API_KEY
openrouterhttps://openrouter.ai/api/v1OPENROUTER_API_KEY
xaihttps://api.x.ai/v1XAI_API_KEY

O preset apifun foi renomeado para apikeyfan. Atualize as chaves provider e providers em configurações existentes; APIFUN_API_KEY permanece como um alias para APIKEYFAN_API_KEY.

Um bloco openrouter de nível superior legado (com baseUrl, translationModels, defaultModel, fallbackModel, maxTokens, temperature, requestTimeout, requestTimeoutMs) ainda é aceito e é migrado automaticamente para providers.openrouter (com provider: "openrouter") no carregamento; defaultModel / fallbackModel se dobram em translationModels.

Para um exemplo executável que configura vários provedores em uma configuração e alterna entre eles com -P, consulte examples/multi-provider (openai, anthropic, openrouter e deepseek no mesmo documento).

Por que usar vários modelos: Diferentes provedores e modelos têm custos variados e oferecem diferentes níveis de qualidade em diferentes idiomas e localidades. Configure o translationModels como uma cadeia de fallback ordenada para que a CLI possa tentar o próximo modelo se uma solicitação falhar. O guia para criar essa lista está em Modelos de IA.

Considere a lista abaixo como um ponto de partida. Substitua-a pela classificação de benchmark em Modelos de IA. Se a tradução para uma localidade específica permanecer de baixa qualidade, adicione uma entrada localeModels para esse idioma ou script, ou adicione outros IDs do catálogo do provedor.

Esses IDs de modelo são o que ai-i18n-tools init -P openrouter escreve. Outras predefinições obtêm IDs de modelo nativos de init -P <provider> — consulte Provedores integrados.

Esta lista foi testada quanto à ampla cobertura de localidades em um grande projeto de documentação com 36 localidades de destino; serve como um padrão prático, mas não há garantia de bom desempenho para todas as localidades.

Exemplo translationModels (lista do OpenRouter de ai-i18n-tools init -P openrouter):

Lista de translationModels do OpenRouter
json
"translationModels": [
  "google/gemini-2.5-flash",
  "meta-llama/llama-3.3-70b-instruct",
  "openai/gpt-4o-mini",
  "google/gemma-4-26b-a4b-it",
  "~anthropic/claude-haiku-latest",
  "z-ai/glm-5.2",
  "google/gemini-3.5-flash",
  "~anthropic/claude-sonnet-latest"
  // … add more fallback models as needed
]

uiModels recomendado: As strings da interface do usuário são curtas, mas altamente visíveis — um modelo premium geralmente melhora o tom, os plurais e a consistência. O uiModels opcional é tentado após qualquer entrada localeModels correspondente e antes do translationModels (consulte a lista de campos acima). Exemplo:

uiModels recomendados para tradução de interface do usuário
json
"uiModels": [
  "~anthropic/claude-sonnet-latest",
  "z-ai/glm-5.2"
]

localeModels recomendado para idiomas asiáticos: Locales japoneses, coreanos e chineses geralmente se beneficiam de modelos ajustados para esses scripts. Adicione substituições por localidade que são tentadas primeiro (antes de uiModels / translationModels) quando a localidade de destino corresponde:

localeModels recomendados para ja, ko, zh-Hans, zh-Hant
json
"localeModels": [
  { "locale": "ja",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "ko",      "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hans", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] },
  { "locale": "zh-Hant", "models": [ "z-ai/glm-5.2", "minimax/minimax-m2.7" ] }
]

Defina a variável de ambiente da chave de API do provedor ativo (consulte a tabela de presets) em seu ambiente ou arquivo .env.

Antes de alterar as listas de modelos, execute ai-i18n-tools check-models. Para qualquer provedor, ele verifica cada ID de modelo configurado (translationModels, uiModels e todas as entradas localeModels) em relação à lista de modelos ativos desse provedor (GET /models), relata IDs ausentes ou que excederam expiration_date, lista os modelos válidos e sai com um código diferente de zero quando qualquer ID configurado é inválido. Quando o provedor retorna preços (por exemplo, OpenRouter), ele também mostra o preço estimado de entrada/saída (USD por 1M de tokens).

Para comparar os modelos configurados em trabalhos de tradução reais, execute ai-i18n-tools bench-models. Ele compara cada ID de modelo exclusivo de translationModels, uiModels e localeModels traduzindo uma amostra por meio de cada um isoladamente (em paralelo, limitado por concurrency) e imprime tokens de entrada/saída por modelo, tempo de execução e custo em USD, para que você possa pesar a velocidade em relação ao preço antes de decidir sobre as listas de modelos.


features ​

CampoPipelineDescrição
translateUIStrings1Extrair t("…") / i18n.t("…") para strings.json, então traduzir entradas e escrever JSON plano por localidade (a extração é executada automaticamente; use extract autônomo para atualizar apenas o catálogo).
translateDocs2Traduz páginas .md / .mdx / .astro / .html / .htm; JSON do shell do Docusaurus quando docs[].docusaurusCatalogDir está definido; _meta / dicionário do Nextra quando configurado; tema do VitePress quando docsOutput.vitepressThemeCatalog está definido; meta.json / catálogo de UI do Fumadocs quando docsOutput.style é "fumadocs".
translateJson3JSON aninhado arbitrário sob json[] (translate-json).
translateSVG—Traduzir arquivos .svg (requer o bloco svg no nível superior).

Cada flag assume o padrão true quando a chave é omitida. O comportamento é:

  • Um true omitido sem nada para traduzir é ignorado: nenhum bloco de UI tem sourceRoots, nenhum bloco de documentos tem contentPaths ou docusaurusCatalogDir, json[] não tem contentPaths, ou svg não está definido.
  • Escrever a flag como true quando esse pipeline não tem trabalho é um erro de configuração.
  • Escrever false desativa esse pipeline para sync mesmo quando as fontes existem.
  • --no-ui, --no-docs, --no-json e --no-svg pulam a etapa para uma execução.

Traduzir arquivos SVG com translate-svg quando features.translateSVG for verdadeiro e um bloco svg de nível superior estiver configurado. O comando sync executa essa etapa quando a flag está ativada e svg está definido (a menos que --no-svg).


ui ​

Um objeto de catálogo ou um array de blocos de catálogo (a mesma ideia de docs[]). Um único objeto é aceito no carregamento e encapsulado em um array de um elemento; o arquivo no disco não é reescrito. Após a análise, config.ui é sempre um array.

extract, translate-ui, sync-ui, a fase de UI de sync, proofread-ui, export-ui-xliff, generate-ui-languages e purge-locale percorrem cada bloco que possui sourceRoots. Passe --ui-block com um índice baseado em zero, o description do bloco ou seu caminho stringsJson para executar um bloco. status e statistics listam cada bloco que possui fontes ou um catálogo existente. O Painel de Tradução lista cada um desses catálogos e mostra um seletor quando há mais de um.

Os caminhos resolvidos de stringsJson, flatOutputDir e de manifesto devem ser exclusivos em todos os blocos. Os valores de description devem ser exclusivos quando definidos, porque --ui-block faz a correspondência exata com eles.

  • description Nota opcional para as pessoas que leem a configuração (não enviada ao modelo). Exibida como ui[i] — description nos cabeçalhos de comando, status, statistics e no painel.
  • sourceRoots Diretórios ou padrões glob (relativos ao cwd) verificados em busca de chamadas t("…"). Suporta padrões como src/ ou ["src/**/*.ts"]. Um bloco com uma lista vazia é ignorado, a menos que --ui-block o nomeie, o que é um erro.
  • stringsJson Caminho para o arquivo de catálogo mestre deste bloco. Atualizado por extract.
  • flatOutputDir Diretório onde os arquivos JSON por localidade deste bloco são gravados (de.json, etc.).
  • flatOutput Quando true (o padrão), translate-ui grava um arquivo JSON plano por localidade. Defina false para emitir apenas gettext ou resx. Um bloco com flatOutput: false deve definir gettext ou resx.
  • resx Saída opcional .NET .resx. outputDir (padrão Resources) e baseName (padrão SharedResource) gravam {baseName}.resx mais {baseName}.{culture}.resx. writeNeutral (padrão true) coloca o texto fonte no arquivo neutro para que ResourceManager possa retornar. localeFormat é bcp47 (padrão, pt-BR) ou posix (pt_BR). ingestExistingResx (padrão true) lê satélites durante a extract. neutralFile mapeia chaves nomeadas legadas como LoginButton através do valor neutro. As chaves de contexto usam U+2404. As formas plurais são entradas separadas nomeadas {singular}[{form}]. Um bloco com flatOutput: false deve definir gettext ou resx.
  • gettext Saída opcional GNU gettext para este bloco. outputDir (padrão ./locales) recebe <locale>/LC_MESSAGES/<domain>.po e, quando compileMo é true (o padrão), o .mo correspondente. domain assume como padrão messages. potPath é o catálogo de modelo. ingestExistingPo (padrão true) preenche slots strings.json vazios com valores msgstr não-fuzzy durante a extract e não substitui uma tradução não vazia ou editada pelo usuário. localeFormat é posix (padrão, pt_BR) ou bcp47 (pt-BR). As linhas contextuais usam o separador \u0004 do gettext. A mesma string de idioma de origem em dois contextos não compartilha um ID de catálogo.
  • targetLocales Lista de localidades opcional para este bloco. Quando omitido ou vazio, o bloco usa a targetLocales raiz.
  • languagesManifestPath Caminho opcional onde extract e generate-ui-languages gravam a ui-languages.json deste bloco. Quando omitido, o bloco 0 usa o languagesManifestPath raiz (que por si só assume como padrão o {flatOutputDir}/ui-languages.json deste bloco). Blocos posteriores assumem como padrão {flatOutputDir}/ui-languages.json.
  • uiGlossary Quando true (o padrão), o strings.json deste bloco é uma fonte de dicas de glossário para translate-docs, translate-json e translate-svg. translate-ui, proofread-ui e a linting de origem usam apenas glossary.userGlossary. Defina false para manter um catálogo fora dessas dicas (por exemplo, um catálogo de strings CLI que não deve direcionar a documentação).
  • uiExtractor.funcNames (ou legado reactExtractor.funcNames) Nomes de funções adicionais para varrer (padrão: ["t", "i18n.t"]).
  • uiExtractor.extensions (ou legado reactExtractor.extensions) Extensões de arquivo a serem incluídas (padrão: [".js", ".jsx", ".ts", ".tsx"]). Adicione .astro para frontmatter e expressões de modelo Astro.
  • uiExtractor.includePackageDescription (ou legado reactExtractor.includePackageDescription) Quando true (padrão), extract também inclui package.json description como uma string de UI quando presente. Defina false em blocos extras para que a mesma descrição não seja extraída em todos os catálogos.
  • uiExtractor.packageJsonPath (ou legado reactExtractor.packageJsonPath) Caminho personalizado para o arquivo package.json usado para essa extração opcional de descrição.
  • uiExtractor.includeUiLanguageEnglishNames (ou legado reactExtractor.includeUiLanguageEnglishNames)

Quando true (padrão false), extract também adiciona cada englishName do catálogo mestre de ui-languages empacotado (construído a partir de sourceLocale + o targetLocales efetivo do bloco) a strings.json quando ainda não presente da varredura da fonte (mesmas chaves de hash). Não lê languagesManifestPath.

  • uiExtractor.placeholderStyledefault (mustache, campos de formato Python e printf) ou dotnet (somente {0}, {0,-10}, {0:format}). No estilo dotnet, um sinal de porcentagem é texto literal e chaves duplas são chaves literais. O modelo ui-dotnet define dotnet.
  • uiExtractor.exclude Padrões minimatch, relativos à raiz do projeto, descartados após a varredura. bin, obj, .vs, TestResults e packages já são ignorados pelo nome do diretório. Os modelos ui-dotnet e ui-dotnet-resx excluem **/Tests/**, **/*.Tests/** e **/TrExtension.cs.

glossary.uiGlossary e glossary.uiGlossaryFromStringsJson não são mais aceitos. O carregamento da configuração falha e o erro explica a substituição: exclua a chave. As dicas agora vêm da flag uiGlossary de cada bloco (padrão true).


cacheDir ​

  • cacheDir Diretório de cache do SQLite (compartilhado por todos os blocos docs). Padrão .translation-cache. Reutilize entre execuções. Se você estiver migrando de um cache de tradução de documentação personalizado, arquive-o ou exclua-o — cacheDir cria seu próprio banco de dados SQLite e não é compatível com outros esquemas. suggest-models também armazena agregados de benchmark em <cacheDir>/benchmark-scores.json. Esse arquivo é um cache, como o restante do diretório, e não faz parte do pacote publicado.

Melhor prática para exclusões no git: ​

  • Exclua o conteúdo da pasta de cache de tradução (por exemplo, usando .gitignore ou .git/info/exclude) para evitar o commit de artefatos de cache temporários.
  • Mantenha cache.db (não o exclua rotineiramente), pois preservar o cache SQLite evita a retradução de segmentos inalterados. Isso economiza custos de tempo de execução e de API ao atualizar ou modificar software que usa ai-i18n-tools.
  • Exclua arquivos de ambiente e arquivos temporários para que segredos e backups não sejam commitados.

Exemplo:

init escreve este bloco para o cacheDir padrão. Quando cacheDir for diferente, as duas linhas de cache usarão esse diretório, por exemplo .i18n-cache/* e !.i18n-cache/cache.db.

gitignore
# Cache
.translation-cache/*
!.translation-cache/cache.db
benchmark-scores.json

# Environment
.env
.env.local
.env.*.local

# Temporary files
*.tmp
*.backup.*

docs ​

Array de blocos de pipeline de documentação. translate-docs e a fase de documentos de sync processam cada bloco em ordem. Chaves legadas ainda são aceitas no momento do carregamento e reescritas quando o arquivo de configuração é gravável; prefira os nomes atuais em novas configurações.

Chave legadaChave/comportamento atual
documentationsdocs
markdownOutputdocs[].docsOutput
jsonSourcedocs[].docusaurusCatalogDir
openrouter de nível superiorproviders.openrouter + provider: "openrouter"
features.translateMarkdownfeatures.translateDocs
features.translateJSONremovido (use docs[].docusaurusCatalogDir ou json[])
features.extractUIStringsremovido (extract é executado antes da tradução da interface do usuário)
glossary.uiGlossary e glossary.uiGlossaryFromStringsJsonremovidos; falha no carregamento da configuração. Use ui[].uiGlossary (booleano, padrão true)
ui.reactExtractorui.uiExtractor (alias ainda aceito)
svg.svgExtractor.forceLowercasesvg.forceLowercase

Fontes de conteúdo

  • description Nota opcional legível por humanos para este bloco (não usada para tradução). É prefixada no título do translate-docs 🌐 quando definida; também exibida nos cabeçalhos das seções status.
  • contentPaths Corpos de páginas em Markdown/MDX e modelos .astro a serem traduzidos (translate-docs examina estes por .md, .mdx e .astro). Suporta caminhos de diretório ou padrões glob (por exemplo, "docs/**/*.md", "guides/*.mdx", "src/pages/index.astro"). É daí que vem o conteúdo textual da documentação localizada.
  • sourceFiles Alias opcional mesclado em contentPaths no carregamento.
  • targetLocales Subconjunto opcional de localidades apenas para este bloco (caso contrário, usa a targetLocales raiz). As localidades efetivas de documentação são a união entre todos os blocos.
  • docusaurusCatalogDir Opcional. Diretório de origem para catálogos de rótulos JSON do Docusaurus para este bloco (por exemplo, "i18n/en" de docusaurus write-translations). Os corpos das páginas sempre vêm de contentPaths; docusaurusCatalogDir apenas fornece JSON de shell/UI, não MDX.
  • nextraMetaGlob Glob(s) opcionais para _meta.ts / _meta.tsx / _meta.js do Nextra em docsRoot. Quando docsOutput.style é "nextra" e isso é omitido, todos os arquivos _meta em docsRoot são coletados automaticamente.
  • nextraMetaTranslatableKeys Nomes de propriedades opcionais cujos valores de string são traduzidos em objetos _meta do Nextra (padrão: title, display, breadcrumb).
  • nextraDictionaryPath Módulo de dicionário de tema Nextra em inglês opcional (por exemplo, "app/_dictionaries/en.ts"). Traduzido para {dir}/{locale}.ts durante translate-docs.
  • nextraDictionaryOutputTemplate Modelo de saída opcional para módulos de dicionário de localidade (padrão: {dir}/{locale}.ts em relação ao diretório do dicionário).

docsOutput ​

Layout de saída para este bloco.

  • outputDir Diretório raiz para a saída traduzida para este bloco.
  • docsOutput.style"nested" (padrão), "flat", "doc-system", ou aliases "docusaurus" / "astro-starlight" / "vitepress" / "nextra".
  • docsOutput.localeSubpath Segmento de caminho entre {locale}/ e {relativeToDocsRoot} para doc-system (obrigatório ao usar style: "doc-system" diretamente; predefinido ao usar um alias). Use "" para pastas de localidade no estilo Starlight.
  • docsOutput.docsRoot Raiz dos documentos de origem para o layout do Docusaurus (por exemplo, "docs"). Padrão "docs" quando omitido.
  • docsOutput.pathTemplate Caminho de saída de markdown personalizado. Espaços reservados: "{outputDir}", "{locale}", "{LOCALE}", "{llocale}", "{relPath}", "{stem}", "{basename}", "{extension}", "{docsRoot}", "{relativeToDocsRoot}".
  • docsOutput.jsonPathTemplate Caminho de saída JSON personalizado para arquivos de rótulo. Suporta os mesmos espaços reservados que pathTemplate.
  • docsOutput.localePathLowercase Quando true, layouts de saída integrados (nested, flat, doc-system sem pathTemplate) usam segmentos de localidade em minúsculas nos caminhos. Padrão false; astro-starlight e doc-system com localeSubpath vazio padronizam para true no carregamento da configuração.
  • docsOutput.flatPreserveRelativeDir Quando docsOutput.style = "flat", mantenha os subdiretórios de origem para que arquivos com o mesmo nome base não colidam. Padrão false.
  • docsOutput.rewriteRelativeLinks Reescrever links relativos após a tradução (ativado automaticamente quando docsOutput.style = "flat" e nenhuma configuração personalizada de pathTemplate).
  • docsOutput.linkRewriteDocsRoot Raiz do repositório usada ao calcular prefixos de reescrita de links diretos. Geralmente, deixe como ".", a menos que sua documentação traduzida esteja em uma raiz de projeto diferente.
  • docsOutput.rewriteVitepressLinks Quando true, execute o normalizador de links do VitePress após a tradução. O padrão é ativado quando docsOutput.style é "vitepress". Use com qualquer layout doc-system onde as pastas de localidade ficam ao lado dos arquivos da localidade de origem em docsRoot. O idioma de origem é sourceLocale e pode ser qualquer idioma. Reescreve caminhos docs/guide/… estilo README para rotas do site (/guide/…) e links ../guide/… relativos à localidade. Para links para arquivos do repositório fora da árvore do VitePress (LICENSE, examples/), use URLs completas nos arquivos da localidade de origem — veja Integração com VitePress — README como a página inicial da documentação.
  • docsOutput.rewriteNextraLinks Quando true, execute o normalizador de links do Nextra após a tradução. O padrão é ativado quando docsOutput.style é "nextra". Reescreve caminhos content/en/… e .mdx relativos para rotas de site neutras em relação à localidade (/guide/…) para Next.js i18n. Veja Integração com Nextra — Convenções de links.
  • docsOutput.fumadocsParser"dot" (padrão) ou "dir". Dot escreve stem.{locale}.mdx ao lado dos arquivos da localidade de origem; dir escreve pastas de localidade como Nextra. O idioma de origem é sourceLocale e pode ser qualquer idioma. Veja Integração com Fumadocs — Layout da página.
  • docsOutput.rewriteFumadocsLinks Quando true, execute o normalizador de links do Fumadocs após a tradução. O padrão é ativado quando docsOutput.style é "fumadocs". Reescreve caminhos de conteúdo e links .mdx relativos para rotas /docs/….
  • docsOutput.fumadocsUiCatalog Opcional. Bootstrap do catálogo de substituição da UI do Fumadocs + tradução dentro de translate-docs. Campos: sourcePath (ex: lib/layout.shared.ts), catalogPath (JSON em inglês gerado), outputPathTemplate opcional (padrão: ui.{locale}.json ao lado de catalogPath).
  • docs[].fumadocsMetaGlob Glob(s) opcionais para coleta de meta.json quando docsOutput.style é "fumadocs". Padrão: meta.json recursivo em docsOutput.docsRoot.
  • docs[].fumadocsMetaTranslatableKeys Nomes de propriedades cujos valores de string são traduzidos no meta.json do Fumadocs (padrão: title, description).
  • docsOutput.localizedAssets Renomeação opcional de URLs de imagens e ícones no HTML traduzido quando existe um arquivo de localidade. Campos: include (padrão img/**), pattern (padrão {stem}-{locale}{ext}), onlyIfExists (padrão true), assetRoot (diretório usado para testar URLs relativas à raiz; o padrão é o diretório do arquivo HTML). Placeholders: {stem}, {ext}, {basename}, {locale}, {llocale}, {LOCALE}. O url() CSS não é reescrito. Consulte páginas HTML.
  • docsOutput.html Lista de idiomas e hreflang opcionais para documentos HTML. Os comentários padrão são <!-- ai-i18n:lang-list --> … <!-- /ai-i18n:lang-list --> e <!-- ai-i18n:hreflang --> … <!-- /ai-i18n:hreflang -->. languageList.format é links ou select. languageList.label é local, english ou both. hreflang.siteUrl prefixa links alternativos; quando omitido, os links são relativos e um aviso é registrado. hreflang.xDefault tem como padrão sourceLocale. hreflang.stripIndexHtml transforma index.html em uma URL de diretório. Para HTML, docsRoot é removido antes que a pasta de localidade seja adicionada (site/index.html → site/{locale}/index.html quando docsRoot é site). Consulte páginas HTML.
  • docsOutput.vitepressThemeCatalog Opcional. Bootstrap de catálogo de tema/nav/sidebar do VitePress + tradução dentro de translate-docs. Campos: configPath (configuração do VitePress com strings do tema), catalogPath (JSON aninhado em inglês gerado), outputPathTemplate opcional (padrão: theme.{locale}.json ao lado de catalogPath).

Pós-processamento

  • docsOutput.postProcessing Transformações opcionais no corpo markdown traduzido (chaves YAML e valores de front matter não-prosa são preservados). Executa após a remontagem do segmento e reescrita de links (flat ou VitePress), e antes de addFrontmatter.
  • docsOutput.postProcessing.regexAdjustments Lista ordenada de { "description"?, "search", "replace" }. search é um padrão regex (string simples usa flag g, ou /pattern/flags). replace suporta placeholders como ${translatedLocale}, ${sourceLocale}, ${sourceFullPath}, ${translatedFullPath}, ${sourceFilename}, ${translatedFilename}, ${sourceBasedir}, ${translatedBasedir}.
  • docsOutput.postProcessing.languageListBlock{ "start", "end", "separator", "label"? } — regenera uma linha de link "ler em outros idiomas" delimitada em markdown de origem e traduzido. Requer languagesManifestPath (ou um manifesto em ui.flatOutputDir/ui-languages.json) para rótulos endônimos quando label: "local".

Comportamento e metadados

  • translateFrontmatterFields Mesmo nível que docsOutput (por bloco docs[]). Padrão true: traduzir a prosa YAML voltada para o usuário para Starlight/Docusaurus (rótulos title, description, sidebar.label, sidebar_label, keywords, hero.title, hero.tagline, hero.image.alt, hero.actions[].text, pagination_label, prev/next). Defina false para manter todo o bloco de front matter inalterado; passe um array de strings para restringir a dot-paths específicos.
  • segmentSplitting Mesmo nível que docsOutput (por bloco docs[]). Segmentos opcionais mais granulares para extração translate-docs: { "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }. Quando enabled é true (padrão quando segmentSplitting é omitido), parágrafos densos, tabelas GFM pipe (o primeiro bloco inclui cabeçalho, separador e a primeira linha de dados) e listas longas são divididos; as subpartes se unem com quebras de linha únicas (tightJoinPrevious). Defina "enabled": false para usar um segmento por bloco de corpo delimitado por linha em branco apenas. Quando qualityRetrySplit é true (padrão), segmentos markdown que falham na validação AST após a lista de modelos parar são divididos progressivamente e retentados a partir do primeiro modelo. A lista para mais cedo quando o mesmo erro de qualidade ocorre três vezes. maxQualityRetrySplitDepth (padrão 3) limita as divisões recursivas.
  • warnMarkdownSourceIssues Quando true (padrão quando omitido), cada execução translate-docs verifica novamente os segmentos markdown em busca de delimitadores de risco / código inline não fechado, imprime avisos no terminal e substitui as linhas markdown_source_issues para o caminho do arquivo de cache desse arquivo. Defina false para pular avisos e atualizações SQLite para este bloco.
  • addFrontmatter Quando true (padrão quando omitido), arquivos markdown traduzidos incluem chaves YAML: translation_last_updated, source_file_mtime, source_file_hash, translation_language, source_file_path, e quando pelo menos um segmento tem metadados do modelo, translation_models (lista ordenada de IDs de modelo do provedor ativo). Defina como false para pular.
  • emphasisPlaceholders Por bloco docs[]. Quando true, mascara os delimitadores de ênfase do markdown como placeholders antes da tradução. O padrão é true para localidades CJK (zh, ja, ko) e para localidades listadas em rtlLocales; caso contrário, o padrão é false. Pode ser substituído via CLI --emphasis-placeholders / --no-emphasis-placeholders.
  • rtlLocales Array opcional de códigos BCP-47 tratados como RTL para padrões de placeholder de ênfase (mesclado com detecção RTL incorporada).

  • protectAttributes Opcional. Nomes adicionais de atributos JSX/HTML cujos valores entre aspas não devem ser enviados ao tradutor. Mesclados com os padrões integrados (class, id, style, src, href, type, data-*, a maioria dos aria-*, etc.). Não diferencia maiúsculas de minúsculas. Aplica-se a:

  • Extração por análise e substituição .astro (etiquetas HTML estáticas e literais de string após attr= dentro de blocos {expression}).

    • Extração de espaços reservados MDX durante a tradução de segmentos markdown/Astro (label, tooltip e aria-label em tags JSX com letras maiúsculas, além de TabItem value quando aplicável).

Exemplo: "protectAttributes": ["variant", "size"] mantém variant="primary" dentro de {items.map(...)} inalterado entre os idiomas.

Você também pode listar atributos normalmente traduzíveis (por exemplo, "title" ou "aria-label") quando desejar que esses valores sejam copiados textualmente do inglês.

  • protectKeys Opcional. Nomes adicionais de propriedades de objeto cujos valores em string entre aspas não devem ser traduzidos dentro de blocos modelo {expression} e literais de objeto MDX (por exemplo, label: dentro de <Tabs values={[ … ]}>). Mesclado com os padrões integrados (class, key, id, href, src, etc.). Não diferencia maiúsculas de minúsculas.

Exemplo: "protectKeys": ["slug", "code"] ignora { slug: 'getting-started', title: 'Getting started' } → apenas title é traduzido quando slug está protegido.


Exemplo (docsOutput.style = "flat" — caminhos de capturas de tela + invólucro opcional com lista de idiomas):

Exemplo de pós-processamento com layout plano (capturas de tela + bloco languageListBlock)
json
"docsOutput": {
  "style": "flat",
  "postProcessing": {
    "regexAdjustments": [
      {
        "description": "Per-locale screenshot folders",
        "search": "images/screenshots/[^/]+/",
        "replace": "images/screenshots/${translatedLocale}/"
      }
    ],
    "languageListBlock": {
      "start": "<small id=\"lang-list\">",
      "end": "</small>",
      "separator": " · ",
      "label": "local"
    }
  }
}

json ​

Matriz de nível superior de pipelines de tradução JSON aninhados. Usado apenas quando features.translateJson é verdadeiro (translate-json ou a etapa JSON de sync). Consulte JSON.

CampoDescrição
descriptionNota opcional para CLI / status (não traduzida).
contentPathsArquivos, diretórios ou globs de origem .json sob a raiz do projeto. Arquivos de namespace i18next típicos (public/locales/en/*.json) são suportados: objetos aninhados, arrays, interpolação {{var}} em valores de string e chaves de sufixo plural independentes (key_one, key_other).
outputPathTemplateCaminho de saída obrigatório por localidade de destino. Substituições: {locale}, {LOCALE}, {llocale}, {stem}, {basename}, {extension}, {relativeToSourceRoot}.
targetLocalesSubconjunto opcional para este bloco; caso contrário, usa a raiz targetLocales.
keyPolicy.modeallowlist, denylist ou both.
keyPolicy.translateKeysCaminhos com ponto / padrões glob a incluir quando o modo for allowlist ou both.
keyPolicy.skipKeysCaminhos com ponto / padrões glob a excluir (a lista de negação padrão inclui id, slug, href, url, key, code).

svg ​

Caminhos e estrutura de nível superior para arquivos SVG. A tradução é executada apenas quando features.translateSVG é verdadeiro (via translate-svg ou o estágio SVG de sync).

CampoDescrição
sourcePathUm ou mais diretórios ou padrões glob (por exemplo, "images/*.svg", "**/icons/*.svg"). Os padrões são resolvidos em relação à raiz do projeto e escaneados recursivamente em busca de arquivos .svg.
outputDirDiretório raiz para a saída de SVG traduzido.
style"flat" ou "nested" quando pathTemplate não estiver definido.
pathTemplateCaminho de saída personalizado para SVG. Substituições: "{outputDir}", "{locale}", "{LOCALE}", "{llocale}", "{relPath}", "{stem}", "{basename}", "{extension}", "{relativeToSourceRoot}".
localePathLowercaseQuando true, os layouts integrados de SVG flat / nested usam segmentos de idioma em letras minúsculas. Valores personalizados de pathTemplate permanecem inalterados; use {llocale} para segmentos em minúsculas.
forceLowercaseTexto traduzido em letras minúsculas na remontagem SVG. Útil para designs que dependem de rótulos totalmente em letras minúsculas.

modelSuggestion (opcional) ​

Pesos ChrF e Arena, além de um piso de qualidade opcional, para suggest-models e a aba Modelos do painel. O índice é apenas de qualidade. Omita o bloco, ou omita um perfil, e esse perfil manterá os pesos integrados. O bloco não é reescrito por --apply ou Atualizar configuração; esses escrevem apenas IDs de modelo. Um peso price herdado em um perfil é removido quando a configuração é carregada.

  • quality — ChrF padrão 0.55, Arena 0.45, piso de qualidade 0.7
  • price — ChrF padrão 0.55, Arena 0.45, piso de qualidade 0.6

Cada objeto de perfil requer chrf e arena. Cada valor é finito e pelo menos 0, e pelo menos um é maior que 0. Eles são normalizados para somar 1, então 55 e 45 correspondem aos padrões. qualityFloor é opcional, no intervalo (0, 1], e é a fração do melhor ChrF no pool de candidatos. Modelos abaixo do piso, incluindo qualquer modelo sem medição de ChrF, são classificados depois daqueles que o superam. Os dois perfis compartilham a mesma mistura padrão; eles diferem na ordem de classificação (--quality por índice, --price por fronteira de Pareto) e no piso.

json
"modelSuggestion": {
  "quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
  "price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}

glossary ​

CampoDescrição
userGlossaryCaminho para um CSV com as colunas Original language string (ou en), locale, Translation, Force opcional e Context opcional - uma linha por termo de origem e localidade de destino (locale pode ser * para todos os destinos).
autoAddUserEditedToGlossaryQuando true, as edições do painel para strings da UI podem ser anexadas automaticamente ao glossário do usuário.
contextFilesArquivos Markdown ou de texto simples (.md, .markdown, .txt) opcionais relativos ao cwd com explicações de produtos ou recursos. Carregados no início do comando e injetados na UI, documentos, JSON, SVG e prompts de revisão. Não coloque esses arquivos em docs[].contentPaths, a menos que você também queira que eles sejam traduzidos. URLs são rejeitadas. O texto completo é enviado ao provedor LLM configurado e pode aparecer nos logs --debug-failed — não inclua segredos ou PII.
contextMaxCharsNúmero máximo de caracteres de texto de arquivo de contexto concatenado enviado ao modelo (padrão 12000, limite máximo 100000). O texto em excesso é truncado com um aviso.
labelCheckSkipsLista opcional de verificações de rótulos de UI bloqueados a serem ignoradas. Cada entrada tem term (termo do glossário em inglês), locales (códigos de destino, ou * para cada localidade; padrão *), files opcional (globs relativos ao cwd) e note opcional. O termo permanece como uma dica de prompt. Uma ignorada se aplica na próxima execução de translate-docs.

translate-docs, translate-json e translate-svg também obtêm sugestões de cada bloco de UI cujo uiGlossary seja true (o padrão). Isso reutiliza traduções já armazenadas no strings.json desse bloco. Defina uiGlossary como false em um bloco para omiti-lo. translate-ui e proofread-ui não usam esses catálogos como sugestões. Abreviações compactas de rótulos de UI (formas com ponto final como Alm., ou compressões curtas de token único como Size → Tam) são ignoradas para que os prompts do documento não sejam direcionados a tokens {{…}} inventados. Termos completos do produto e traduções de UI não abreviadas continuam sendo usados como sugestões.

A coluna CSV opcional Context é um guia de uso na língua de origem para aquele termo (definição, uso gramatical, significado do produto). Ela é incluída apenas quando o termo corresponde ao lote atual. Alterar a nota Context de um termo ou qualquer conteúdo contextFiles invalida os segmentos em cache da localidade correspondente e as linhas de rastreamento de arquivo na próxima execução, então as traduções são atualizadas automaticamente. Alterar apenas um Translation preferencial em uma linha não forçada ainda usa o cache existente, a menos que você passe --force / --force-update. Uma linha Force perde apenas os segmentos cuja origem contém aquele termo, quando o texto armazenado ainda não inclui a tradução forçada. As linhas de cache editadas pelo usuário do painel são mantidas. Os catálogos de UI também semeiam um prefixo de várias palavras compartilhado como seu próprio termo quando esse prefixo é um rótulo capitalizado (pelo menos duas palavras de conteúdo) e a tradução compartilhada é uma frase curta sem um placeholder. A tradução de Markdown requer um rótulo de UI de duas a cinco palavras para manter sua tradução de catálogo quando a origem o cita como todo o trecho em negrito ou código inline, em um cabeçalho ou em uma linha que é apenas esse rótulo. Uma frase em negrito mais longa que apenas contém o termo é uma dica. O uso de maiúsculas e minúsculas dentro de uma frase é uma dica, então a tradução pode ser flexionada (Cursor account em hindi pode se tornar कर्सर खाते em vez da forma de dicionário कर्सर खाता). Um rótulo com uma única palavra de conteúdo, como Sign in, permanece uma dica. A verificação ignora a capitalização. Ela ainda exige a redação do catálogo como uma substring, então uma forma gramaticalmente flexionada pode falhar. Essa falha é um aviso: o segmento é escrito, armazenado em cache com um sinalizador de rótulo de glossário e listado no final da execução em glossary-review-*.md sob cacheDir. Adicione uma entrada labelCheckSkips ou passe --recheck-glossary-warnings depois de revisá-lo. --force retraduz as linhas sinalizadas junto com todos os outros segmentos.

Exemplo:

json
{
  "glossary": {
    "userGlossary": "i18n/glossary.csv",
    "contextFiles": ["i18n/product-context.md", "i18n/billing-feature.md"],
    "contextMaxChars": 12000,
    "labelCheckSkips": [
      {
        "term": "Target language",
        "locales": ["uk"],
        "files": ["website/src/content/docs/docs/transform.md"],
        "note": "Inflected inside a bold phrase"
      }
    ]
  }
}

Gere um arquivo CSV de glossário vazio:

bash
ai-i18n-tools glossary-generate

Para criar um rascunho de contextFiles a partir do repositório, use o prompt de copiar e colar do agente em Gerar um arquivo de contexto com um agente de IA. Consulte o Glossário para saber como as linhas de termos e os arquivos de contexto são aplicados.

Lançado sob a Licença MIT.