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 emsrc/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:
{
"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:
{
"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:
translationModelsLista ordenada preferencial de IDs de modelo (IDs upstream simples, sem prefixoprovider/; IDs do OpenRouter mantêm sua forma nativavendor/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 paratranslate-ui, geração de plural (Etapa 0 e Passagem B) eproofread-ui. Tentada após qualquer entradalocaleModelscorrespondente para o local de destino, antes detranslationModels.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 (uiModelspara UI) etranslationModels. Chaves de local normalizadas duplicadas são rejeitadas no carregamento da configuração.baseUrlURL base compatível com OpenAI. Substitui a URL base predefinida; necessária para um provedor não predefinido.apiKeyEnvVariável de ambiente que contém a chave da API. Substitui a variável de ambiente predefinida.headersCabeçalhos HTTP extras enviados com cada solicitação para este provedor.maxTokensMáximo de tokens de conclusão por solicitação. Padrão:8192.temperatureTemperatura de amostragem. Padrão:0.2.requestTimeoutTempo máximo em segundos para aguardar cada solicitação a este provedor. Substitui orequestTimeout/requestTimeoutMsde nível superior. Quando nem este provedor nem a configuração de nível superior definem um tempo limite, o padrão é120segundos. Defina apenas um derequestTimeouterequestTimeoutMsno mesmo objeto.requestTimeoutMsTempo máximo em milissegundos para aguardar cada solicitação a este provedor. Substitui orequestTimeout/requestTimeoutMsde 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 derequestTimeouterequestTimeoutMsno 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 temusage.costrelatado 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 linhaapi_calls.
A fonte de custo é resolvida nesta ordem:
- uma entrada
modelPricingcorrespondente (substitui o padrão deste provedor); - um custo relatado pelo provedor (nunca substituído);
- esta taxa
pricing; - 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 } }. Substituipricingpara esse ID de modelo. Aplicado no momento da chamada quando o provedor omitiuusage.cost, e armazenado com a chamada.zeroDataRetention(opcional, apenasproviders.cheaperinference) Quandotrue, as solicitações de chat enviam"zdr": trueelist-models,check-modelsesuggest-modelscarregamGET /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):
| Provedor | URL base | Variável de ambiente da chave de API |
|---|---|---|
alibaba | https://dashscope-intl.aliyuncs.com/compatible-mode/v1 | ALIBABA_API_KEY |
anthropic | https://api.anthropic.com/v1 | ANTHROPIC_API_KEY |
apikeyfan | https://api.apikey.fan/v1 | APIKEYFAN_API_KEY |
cerebras | https://api.cerebras.ai/v1 | CEREBRAS_API_KEY |
cheaperinference | https://api.cheaperinference.com/v1 | CHEAPERINFERENCE_API_KEY |
deepseek | https://api.deepseek.com | DEEPSEEK_API_KEY |
gemini | https://generativelanguage.googleapis.com/v1beta/openai | GOOGLE_API_KEY |
groq | https://api.groq.com/openai/v1 | GROQ_API_KEY |
mistral | https://api.mistral.ai/v1 | MISTRAL_API_KEY |
nvidia | https://integrate.api.nvidia.com/v1 | NVIDIA_API_KEY |
ollama | http://localhost:11434/v1 | (nenhum) |
openai | https://api.openai.com/v1 | OPENAI_API_KEY |
openrouter | https://openrouter.ai/api/v1 | OPENROUTER_API_KEY |
xai | https://api.x.ai/v1 | XAI_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
"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
"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
"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
| Campo | Pipeline | Descrição |
|---|---|---|
translateUIStrings | 1 | Extrair 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). |
translateDocs | 2 | Traduz 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". |
translateJson | 3 | JSON 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
trueomitido sem nada para traduzir é ignorado: nenhum bloco de UI temsourceRoots, nenhum bloco de documentos temcontentPathsoudocusaurusCatalogDir,json[]não temcontentPaths, ousvgnão está definido. - Escrever a flag como
truequando esse pipeline não tem trabalho é um erro de configuração. - Escrever
falsedesativa esse pipeline parasyncmesmo quando as fontes existem. --no-ui,--no-docs,--no-jsone--no-svgpulam 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.
descriptionNota opcional para as pessoas que leem a configuração (não enviada ao modelo). Exibida comoui[i] — descriptionnos cabeçalhos de comando,status,statisticse no painel.sourceRootsDiretórios ou padrões glob (relativos ao cwd) verificados em busca de chamadast("…"). Suporta padrões comosrc/ou["src/**/*.ts"]. Um bloco com uma lista vazia é ignorado, a menos que--ui-blocko nomeie, o que é um erro.stringsJsonCaminho para o arquivo de catálogo mestre deste bloco. Atualizado porextract.flatOutputDirDiretório onde os arquivos JSON por localidade deste bloco são gravados (de.json, etc.).flatOutputQuandotrue(o padrão),translate-uigrava um arquivo JSON plano por localidade. Definafalsepara emitir apenas gettext ou resx. Um bloco comflatOutput: falsedeve definirgettextouresx.resxSaída opcional .NET.resx.outputDir(padrãoResources) ebaseName(padrãoSharedResource) gravam{baseName}.resxmais{baseName}.{culture}.resx.writeNeutral(padrão true) coloca o texto fonte no arquivo neutro para queResourceManagerpossa retornar.localeFormatébcp47(padrão,pt-BR) ouposix(pt_BR).ingestExistingResx(padrão true) lê satélites durante aextract.neutralFilemapeia chaves nomeadas legadas comoLoginButtonatravés do valor neutro. As chaves de contexto usam U+2404. As formas plurais são entradas separadas nomeadas{singular}[{form}]. Um bloco comflatOutput: falsedeve definirgettextouresx.gettextSaída opcional GNU gettext para este bloco.outputDir(padrão./locales) recebe<locale>/LC_MESSAGES/<domain>.poe, quandocompileMoé true (o padrão), o.mocorrespondente.domainassume como padrãomessages.potPathé o catálogo de modelo.ingestExistingPo(padrãotrue) preenche slotsstrings.jsonvazios com valoresmsgstrnão-fuzzy durante aextracte não substitui uma tradução não vazia ou editada pelo usuário.localeFormatéposix(padrão,pt_BR) oubcp47(pt-BR). As linhas contextuais usam o separador\u0004do gettext. A mesma string de idioma de origem em dois contextos não compartilha um ID de catálogo.targetLocalesLista de localidades opcional para este bloco. Quando omitido ou vazio, o bloco usa atargetLocalesraiz.languagesManifestPathCaminho opcional ondeextractegenerate-ui-languagesgravam aui-languages.jsondeste bloco. Quando omitido, o bloco 0 usa olanguagesManifestPathraiz (que por si só assume como padrão o{flatOutputDir}/ui-languages.jsondeste bloco). Blocos posteriores assumem como padrão{flatOutputDir}/ui-languages.json.uiGlossaryQuandotrue(o padrão), ostrings.jsondeste bloco é uma fonte de dicas de glossário paratranslate-docs,translate-jsonetranslate-svg.translate-ui,proofread-uie a linting de origem usam apenasglossary.userGlossary. Definafalsepara 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 legadoreactExtractor.funcNames) Nomes de funções adicionais para varrer (padrão:["t", "i18n.t"]).uiExtractor.extensions(ou legadoreactExtractor.extensions) Extensões de arquivo a serem incluídas (padrão:[".js", ".jsx", ".ts", ".tsx"]). Adicione.astropara frontmatter e expressões de modelo Astro.uiExtractor.includePackageDescription(ou legadoreactExtractor.includePackageDescription) Quandotrue(padrão),extracttambém incluipackage.jsondescriptioncomo uma string de UI quando presente. Definafalseem blocos extras para que a mesma descrição não seja extraída em todos os catálogos.uiExtractor.packageJsonPath(ou legadoreactExtractor.packageJsonPath) Caminho personalizado para o arquivopackage.jsonusado para essa extração opcional de descrição.uiExtractor.includeUiLanguageEnglishNames(ou legadoreactExtractor.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) oudotnet(somente{0},{0,-10},{0:format}). No estilodotnet, um sinal de porcentagem é texto literal e chaves duplas são chaves literais. O modeloui-dotnetdefinedotnet.uiExtractor.excludePadrões minimatch, relativos à raiz do projeto, descartados após a varredura.bin,obj,.vs,TestResultsepackagesjá são ignorados pelo nome do diretório. Os modelosui-dotneteui-dotnet-resxexcluem**/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
cacheDirDiretório de cache do SQLite (compartilhado por todos os blocosdocs). 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 —cacheDircria seu próprio banco de dados SQLite e não é compatível com outros esquemas.suggest-modelstambé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
.gitignoreou.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 usaai-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.
# 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 legada | Chave/comportamento atual |
|---|---|
documentations | docs |
markdownOutput | docs[].docsOutput |
jsonSource | docs[].docusaurusCatalogDir |
openrouter de nível superior | providers.openrouter + provider: "openrouter" |
features.translateMarkdown | features.translateDocs |
features.translateJSON | removido (use docs[].docusaurusCatalogDir ou json[]) |
features.extractUIStrings | removido (extract é executado antes da tradução da interface do usuário) |
glossary.uiGlossary e glossary.uiGlossaryFromStringsJson | removidos; falha no carregamento da configuração. Use ui[].uiGlossary (booleano, padrão true) |
ui.reactExtractor | ui.uiExtractor (alias ainda aceito) |
svg.svgExtractor.forceLowercase | svg.forceLowercase |
Fontes de conteúdo
descriptionNota opcional legível por humanos para este bloco (não usada para tradução). É prefixada no título dotranslate-docs🌐quando definida; também exibida nos cabeçalhos das seçõesstatus.contentPathsCorpos de páginas em Markdown/MDX e modelos.astroa serem traduzidos (translate-docsexamina estes por.md,.mdxe.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.sourceFilesAlias opcional mesclado emcontentPathsno carregamento.targetLocalesSubconjunto opcional de localidades apenas para este bloco (caso contrário, usa atargetLocalesraiz). As localidades efetivas de documentação são a união entre todos os blocos.docusaurusCatalogDirOpcional. Diretório de origem para catálogos de rótulos JSON do Docusaurus para este bloco (por exemplo,"i18n/en"dedocusaurus write-translations). Os corpos das páginas sempre vêm decontentPaths;docusaurusCatalogDirapenas fornece JSON de shell/UI, não MDX.nextraMetaGlobGlob(s) opcionais para_meta.ts/_meta.tsx/_meta.jsdo Nextra emdocsRoot. QuandodocsOutput.styleé"nextra"e isso é omitido, todos os arquivos_metaemdocsRootsão coletados automaticamente.nextraMetaTranslatableKeysNomes de propriedades opcionais cujos valores de string são traduzidos em objetos_metado Nextra (padrão:title,display,breadcrumb).nextraDictionaryPathMódulo de dicionário de tema Nextra em inglês opcional (por exemplo,"app/_dictionaries/en.ts"). Traduzido para{dir}/{locale}.tsdurantetranslate-docs.nextraDictionaryOutputTemplateModelo de saída opcional para módulos de dicionário de localidade (padrão:{dir}/{locale}.tsem relação ao diretório do dicionário).
docsOutput
Layout de saída para este bloco.
outputDirDiretó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.localeSubpathSegmento de caminho entre{locale}/e{relativeToDocsRoot}paradoc-system(obrigatório ao usarstyle: "doc-system"diretamente; predefinido ao usar um alias). Use""para pastas de localidade no estilo Starlight.docsOutput.docsRootRaiz dos documentos de origem para o layout do Docusaurus (por exemplo,"docs"). Padrão"docs"quando omitido.docsOutput.pathTemplateCaminho de saída de markdown personalizado. Espaços reservados:"{outputDir}","{locale}","{LOCALE}","{llocale}","{relPath}","{stem}","{basename}","{extension}","{docsRoot}","{relativeToDocsRoot}".docsOutput.jsonPathTemplateCaminho de saída JSON personalizado para arquivos de rótulo. Suporta os mesmos espaços reservados quepathTemplate.docsOutput.localePathLowercaseQuandotrue, layouts de saída integrados (nested,flat,doc-systemsempathTemplate) usam segmentos de localidade em minúsculas nos caminhos. Padrãofalse;astro-starlightedoc-systemcomlocaleSubpathvazio padronizam paratrueno carregamento da configuração.docsOutput.flatPreserveRelativeDirQuandodocsOutput.style = "flat", mantenha os subdiretórios de origem para que arquivos com o mesmo nome base não colidam. Padrãofalse.docsOutput.rewriteRelativeLinksReescrever links relativos após a tradução (ativado automaticamente quandodocsOutput.style = "flat"e nenhuma configuração personalizada depathTemplate).docsOutput.linkRewriteDocsRootRaiz 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.rewriteVitepressLinksQuandotrue, execute o normalizador de links do VitePress após a tradução. O padrão é ativado quandodocsOutput.styleé"vitepress". Use com qualquer layoutdoc-systemonde as pastas de localidade ficam ao lado dos arquivos da localidade de origem emdocsRoot. O idioma de origem ésourceLocalee pode ser qualquer idioma. Reescreve caminhosdocs/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.rewriteNextraLinksQuandotrue, execute o normalizador de links do Nextra após a tradução. O padrão é ativado quandodocsOutput.styleé"nextra". Reescreve caminhoscontent/en/…e.mdxrelativos para rotas de site neutras em relação à localidade (/guide/…) para Next.jsi18n. Veja Integração com Nextra — Convenções de links.docsOutput.fumadocsParser"dot"(padrão) ou"dir". Dot escrevestem.{locale}.mdxao lado dos arquivos da localidade de origem; dir escreve pastas de localidade como Nextra. O idioma de origem ésourceLocalee pode ser qualquer idioma. Veja Integração com Fumadocs — Layout da página.docsOutput.rewriteFumadocsLinksQuandotrue, execute o normalizador de links do Fumadocs após a tradução. O padrão é ativado quandodocsOutput.styleé"fumadocs". Reescreve caminhos de conteúdo e links.mdxrelativos para rotas/docs/….docsOutput.fumadocsUiCatalogOpcional. Bootstrap do catálogo de substituição da UI do Fumadocs + tradução dentro detranslate-docs. Campos:sourcePath(ex:lib/layout.shared.ts),catalogPath(JSON em inglês gerado),outputPathTemplateopcional (padrão:ui.{locale}.jsonao lado decatalogPath).docs[].fumadocsMetaGlobGlob(s) opcionais para coleta demeta.jsonquandodocsOutput.styleé"fumadocs". Padrão:meta.jsonrecursivo emdocsOutput.docsRoot.docs[].fumadocsMetaTranslatableKeysNomes de propriedades cujos valores de string são traduzidos nometa.jsondo Fumadocs (padrão:title,description).docsOutput.localizedAssetsRenomeação opcional de URLs de imagens e ícones no HTML traduzido quando existe um arquivo de localidade. Campos:include(padrãoimg/**),pattern(padrão{stem}-{locale}{ext}),onlyIfExists(padrãotrue),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}. Ourl()CSS não é reescrito. Consulte páginas HTML.docsOutput.htmlLista 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élinksouselect.languageList.labelélocal,englishouboth.hreflang.siteUrlprefixa links alternativos; quando omitido, os links são relativos e um aviso é registrado.hreflang.xDefaulttem como padrãosourceLocale.hreflang.stripIndexHtmltransformaindex.htmlem uma URL de diretório. Para HTML,docsRooté removido antes que a pasta de localidade seja adicionada (site/index.html→site/{locale}/index.htmlquandodocsRootésite). Consulte páginas HTML.docsOutput.vitepressThemeCatalogOpcional. Bootstrap de catálogo de tema/nav/sidebar do VitePress + tradução dentro detranslate-docs. Campos:configPath(configuração do VitePress com strings do tema),catalogPath(JSON aninhado em inglês gerado),outputPathTemplateopcional (padrão:theme.{locale}.jsonao lado decatalogPath).
Pós-processamento
docsOutput.postProcessingTransformaçõ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 deaddFrontmatter.docsOutput.postProcessing.regexAdjustmentsLista ordenada de{ "description"?, "search", "replace" }.searché um padrão regex (string simples usa flagg, ou/pattern/flags).replacesuporta 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. RequerlanguagesManifestPath(ou um manifesto emui.flatOutputDir/ui-languages.json) para rótulos endônimos quandolabel: "local".
Comportamento e metadados
translateFrontmatterFieldsMesmo nível quedocsOutput(por blocodocs[]). Padrãotrue: traduzir a prosa YAML voltada para o usuário para Starlight/Docusaurus (rótulostitle,description,sidebar.label,sidebar_label,keywords,hero.title,hero.tagline,hero.image.alt,hero.actions[].text,pagination_label,prev/next). Definafalsepara manter todo o bloco de front matter inalterado; passe um array de strings para restringir a dot-paths específicos.segmentSplittingMesmo nível quedocsOutput(por blocodocs[]). Segmentos opcionais mais granulares para extraçãotranslate-docs:{ "enabled", "maxCharsPerSegment"?, "splitPipeTables"?, "splitDenseParagraphs"?, "maxLinesPerParagraphChunk"?, "splitLongLists"?, "maxListItemsPerChunk"?, "qualityRetrySplit"?, "maxQualityRetrySplitDepth"? }. Quandoenabledétrue(padrão quandosegmentSplittingé 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": falsepara usar um segmento por bloco de corpo delimitado por linha em branco apenas. QuandoqualityRetrySplité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ão3) limita as divisões recursivas.warnMarkdownSourceIssuesQuandotrue(padrão quando omitido), cada execuçãotranslate-docsverifica novamente os segmentos markdown em busca de delimitadores de risco / código inline não fechado, imprime avisos no terminal e substitui as linhasmarkdown_source_issuespara o caminho do arquivo de cache desse arquivo. Definafalsepara pular avisos e atualizações SQLite para este bloco.addFrontmatterQuandotrue(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 comofalsepara pular.emphasisPlaceholdersPor blocodocs[]. Quandotrue, mascara os delimitadores de ênfase do markdown como placeholders antes da tradução. O padrão étruepara localidades CJK (zh,ja,ko) e para localidades listadas emrtlLocales; caso contrário, o padrão éfalse. Pode ser substituído via CLI--emphasis-placeholders/--no-emphasis-placeholders.rtlLocalesArray opcional de códigos BCP-47 tratados como RTL para padrões de placeholder de ênfase (mesclado com detecção RTL incorporada).
protectAttributesOpcional. 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 dosaria-*, 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ósattr=dentro de blocos{expression}).- Extração de espaços reservados MDX durante a tradução de segmentos markdown/Astro (
label,tooltipearia-labelem tags JSX com letras maiúsculas, além deTabItemvaluequando aplicável).
- Extração de espaços reservados MDX durante a tradução de segmentos markdown/Astro (
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.
protectKeysOpcional. 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)
"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.
| Campo | Descrição |
|---|---|
description | Nota opcional para CLI / status (não traduzida). |
contentPaths | Arquivos, 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). |
outputPathTemplate | Caminho de saída obrigatório por localidade de destino. Substituições: {locale}, {LOCALE}, {llocale}, {stem}, {basename}, {extension}, {relativeToSourceRoot}. |
targetLocales | Subconjunto opcional para este bloco; caso contrário, usa a raiz targetLocales. |
keyPolicy.mode | allowlist, denylist ou both. |
keyPolicy.translateKeys | Caminhos com ponto / padrões glob a incluir quando o modo for allowlist ou both. |
keyPolicy.skipKeys | Caminhos 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).
| Campo | Descrição |
|---|---|
sourcePath | Um 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. |
outputDir | Diretório raiz para a saída de SVG traduzido. |
style | "flat" ou "nested" quando pathTemplate não estiver definido. |
pathTemplate | Caminho de saída personalizado para SVG. Substituições: "{outputDir}", "{locale}", "{LOCALE}", "{llocale}", "{relPath}", "{stem}", "{basename}", "{extension}", "{relativeToSourceRoot}". |
localePathLowercase | Quando 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. |
forceLowercase | Texto 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ão0.55, Arena0.45, piso de qualidade0.7price— ChrF padrão0.55, Arena0.45, piso de qualidade0.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.
"modelSuggestion": {
"quality": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.7 },
"price": { "chrf": 0.55, "arena": 0.45, "qualityFloor": 0.6 }
}glossary
| Campo | Descrição |
|---|---|
userGlossary | Caminho 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). |
autoAddUserEditedToGlossary | Quando true, as edições do painel para strings da UI podem ser anexadas automaticamente ao glossário do usuário. |
contextFiles | Arquivos 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. |
contextMaxChars | Nú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. |
labelCheckSkips | Lista 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:
{
"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:
ai-i18n-tools glossary-generatePara 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.