Documentos
Referência para translate-docs, o pipeline para páginas em Markdown, MDX, .astro e HTML simples listadas nos blocos de configuração docs[]. O campo contentPaths de cada bloco lista os arquivos ou pastas a serem traduzidos. Esses arquivos são escritos em sourceLocale, que pode ser qualquer idioma. O inglês nos exemplos é apenas uma amostra. Adicionando idiomas a um site pela primeira vez? Comece em Adicionar i18n a um site ou site de documentação. Um README de repositório e outros arquivos Markdown, geralmente ao lado de um aplicativo: Adicionar i18n ao seu README e documentos Markdown. Páginas HTML simples (um arquivo por localidade) são descritas em Páginas HTML.
As strings do shell do framework (barra de navegação, barra lateral, tema) são traduzidas na mesma execução, não por um pipeline separado. Os guias do framework na tabela abaixo dizem como cada um faz isso: docusaurusCatalogDir para Docusaurus, docsOutput.vitepressThemeCatalog para VitePress, docs[].nextraDictionaryPath para Nextra, docsOutput.fumadocsUiCatalog para Fumadocs. Os rótulos da barra lateral do Nextra _meta.ts e do Fumadocs meta.json são coletados automaticamente. O Astro Starlight vem com strings de UI integradas para muitas localidades, e substituições (overrides) opcionais podem usar jsonPathTemplate em um bloco docs[].
Para PNG e outras imagens raster incorporadas em markdown, consulte Imagens e Capturas de Tela. translate-docs traduz apenas o texto alternativo; ele não copia arquivos raster.
Para um bloco opcional de troca de idioma no README ou na documentação, defina docsOutput.style como "flat" - veja Troca de idioma.
Arquivos SVG são traduzidos via translate-svg quando features.translateSVG está habilitado - não através de docs[] / contentPaths.
Pacotes JSON de UI aninhados arbitrários não relacionados às strings de shell/tema de um framework de documentação pertencem ao pipeline JSON, não ao docs[].
Cada bloco de UI inclui seu strings.json como dicas de glossário para documentação por padrão (uiGlossary, padrão true). translate-docs reutiliza essas traduções como dicas em prompts de LLM quando termos correspondentes aparecem em um segmento. Defina uiGlossary como false em um catálogo que não deve ser incluído nos prompts de documentos. glossary.userGlossary opcional adiciona substituições em CSV para termos do produto (compartilhadas com translate-ui e proofread-ui). As abreviações compactas de rótulos de UI usadas para caber em colunas estreitas (por exemplo, Size → Tam) permanecem disponíveis para a tradução da UI, mas são omitidas das dicas do glossário de documentos. Gere um CSV inicial com glossary-generate, edite as linhas na aba Glossário do Painel de Tradução ou consulte Configuração — glossary e Glossário.
Substituições de modelo por localidade
translate-docs e a etapa de docs de sync resolvem modelos por localidade de destino: primeiro localeModels(locale) quando configurado, depois a cadeia translationModels global do provedor. Use isso quando um idioma específico precisar de um modelo diferente da sua lista de fallback padrão. Por exemplo, preferir o Gemini para a documentação em pt-BR quando a cadeia global tiver dificuldades com o português. Consulte Modelos de IA e Configuração - localeModels.
Qual guia ler
| Sua configuração | Comece aqui |
|---|---|
| Site Docusaurus | init -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus |
| Site VitePress | init -t ui-vitepress + vitepressThemeCatalog para tema - VitePress |
| Site Nextra | init -t ui-nextra + nextraDictionaryPath para dicionário (barra lateral _meta.ts é automática) - Nextra |
| Site Fumadocs | init -t ui-fumadocs + fumadocsUiCatalog para UI (barra lateral meta.json é automática) - Fumadocs |
| Astro Starlight | init -t ui-starlight - Astro Starlight |
| Páginas HTML puras | init -t docs-plain-html - Páginas HTML |
| Documentos simples (README, changelogs, etc.) | Adicionar i18n ao seu README e documentos Markdown — init -t docs-markdown ou --with-readme. Layout: Layouts de saída, seletor de idioma |
| Onde os arquivos traduzidos são salvos | Layouts de saída |
Links #anchor entre páginas | Links de âncora |
Reescrita de URL de link e ativo (regexAdjustments) | Reescrita de link |
| Capturas de tela na documentação | Imagens e Capturas de Tela |
| Terminologia do produto e consistência entre IU e documentação | Configuração — glossary, Glossário |
Sinalizadores e cache translate-docs | Opções da CLI |
Passo 1: Inicializar para documentação
ai-i18n-tools init -t ui-docusaurus -P openaiPara sites de documentação Astro Starlight:
ai-i18n-tools init -t ui-starlight -P cheaperinferencePara sites de documentação VitePress:
ai-i18n-tools init -t ui-vitepress -P anthropicDefina docsOutput.vitepressThemeCatalog para strings de navegação/barra lateral/rodapé - veja Integração VitePress.
Para sites de documentação Nextra:
ai-i18n-tools init -t ui-nextra -P geminiDefina docs[].nextraDictionaryPath para strings de dicionário de tema - veja Integração Nextra. Os rótulos da barra lateral _meta.ts são coletados automaticamente.
Para sites de documentação Fumadocs:
ai-i18n-tools init -t ui-fumadocs -P groqDefina docsOutput.fumadocsUiCatalog para substituições de UI - veja Integração Fumadocs. Os rótulos da barra lateral meta.json são coletados automaticamente.
Para interface de site Astro simples (sem Starlight):
ai-i18n-tools init -t ui-astro-website -P ollamaEsse template habilita apenas a extração de UI. Para a tradução do HTML da página, defina também features.translateDocs e adicione um bloco docs[] (consulte Páginas de site Astro (analisar e substituir)). A configuração examples/astro-website mostra ambos os pipelines juntos.
Edite o ai-i18n-tools.config.json gerado:
providereproviders—init -P <provider>gera a estrutura dessa predefinição; defina a chave de API dele antes detranslate-docsousync(Ollama não precisa de chave). Consulte Provedor e chave de API, Provedores de LLM e Modelos de IA.sourceLocale- idioma de origem (deve corresponder adefaultLocaleemdocusaurus.config.js).targetLocales- array de códigos de localidade BCP-47 (ex.:["de", "fr", "es"]).cacheDir- diretório de cache SQLite compartilhado para todos os pipelines (e diretório de log padrão para--write-logs).docs- array de blocos de documentação. Cada bloco temdescriptionopcional,contentPaths(string ou array; arquivo, diretório ou glob),outputDir,docusaurusCatalogDiropcional,docsOutput,segmentSplittingopcional,translateFrontmatterFields,protectAttributes,protectKeys,targetLocales,addFrontmatter, etc.docs[].description- nota curta opcional para mantenedores. Quando definida, ela aparece no títulotranslate-docse nos cabeçalhos de seçãostatus.docs[].contentPaths- fontes markdown/MDX/.astro(edocusaurusCatalogDiropcional para JSON de shell Docusaurus).docs[].outputDir- raiz de saída traduzida para esse bloco.docs[].docsOutput.style-"nested"(padrão),"flat","doc-system"ou aliases"docusaurus"/"astro-starlight"/"vitepress"/"nextra"/"fumadocs"(consulte Layouts de saída).ui[].uiGlossary- quandotrue(o padrão), ostrings.jsondesse bloco fornece dicas de terminologia para segmentos de documentos (consulte Configuração —ui).glossary.userGlossary- CSV opcional para traduções fixas de termos do produto; também utilizado por pipelines de UI e editável na aba Glossário do painel.
Primário vs complementar: Foque em contentPaths para páginas localizadas. Defina docusaurusCatalogDir quando também precisar do JSON do shell Docusaurus de write-translations. Omita docusaurusCatalogDir se estiver traduzindo apenas páginas.
Passo 2: Traduzir documentos
ai-i18n-tools translate-docsIsso traduz todos os arquivos em cada docs[] do bloco contentPaths (e o JSON do catálogo Docusaurus quando docusaurusCatalogDir é definido) para todos os locais de documentação efetivos. Segmentos já traduzidos são servidos do cache SQLite - apenas segmentos novos ou alterados são enviados para o LLM.
Para traduzir um único idioma:
ai-i18n-tools translate-docs --locale dePara verificar o que precisa ser traduzido:
ai-i18n-tools statusPara sinalizadores, comportamento de cache e formato de prompt em lote, consulte opções da CLI.
Markdown complexo e falhas nas verificações de qualidade
translate-docs verifica se cada segmento traduzido preserva a estrutura Markdown (incluindo a ênfase analisada do documento) e se os tokens de espaço reservado internos são restaurados de forma limpa. Parágrafos que empilham muitos spans bold em torno de `inline code`, aninham crases dentro de negrito (por exemplo, literais de modelo como `fetch(\`/locales/${code}.json\`)`), ou entrelaçam negrito e código em uma frase longa são frágeis: alguns locais precisam de uma ordem de palavras diferente, o que pode mudar como ** e ` se alinham após a tradução e acionar erros de CLI como AST mismatch.
Após a restauração, o translate-docs também rejeita segmentos onde os placeholders de tags HTML foram reutilizados ou descartados (de modo que as tags restauradas não correspondem mais ao mapa de origem) ou onde o modelo inventou tokens de chaves duplas restantes que não estavam na origem (por exemplo, um token de estilo de glossário inventado). As verificações pré-restauração exigem o mesmo multiconjunto de tokens {{…}} e a mesma subsequência ordenada de tokens estruturais ({{HTM_N}}, marcadores de advertência); tokens de conteúdo como {{ILC_N}}, {{URL_N}} e marcadores de ênfase como {{SE}} podem se mover com a ordem natural das palavras quando cada ID/contagem de tipo ainda corresponde. Essas falhas usam o mesmo caminho de fallback do modelo que os tokens internos oficiais restantes.
Se você encontrar esse tipo de falha de validação, prefira simplificar o texto no idioma de origem - divida o parágrafo, mova um exemplo para um bloco de código cercado ou descreva a mesma ideia com menos pares de negrito/código em camadas - em vez de esperar que cada modelo e local reproduza a marcação densa em linha perfeitamente.
Quando os modelos tentados para um segmento falham com um AST mismatch, translate-docs pode dividir automaticamente esse segmento em partes menores (primeiro o ponto médio da lista, depois itens de lista únicos ou blocos de parágrafo mais curtos), tentar novamente cada parte a partir do primeiro modelo e reunir o resultado sob a chave de cache do segmento original. O mesmo erro de qualidade três vezes interrompe a lista de modelos precocemente; um erro diferente continua. Isso está ativado por padrão (segmentSplitting.qualityRetrySplit); defina-o como false para parar depois que a lista de modelos terminar. O resumo da execução relata Quality split retries quando este fallback é executado.
Para ver quais segmentos falharam, com que frequência e as mensagens de qualidade/erro armazenadas, use a guia Falhas do Painel de Tradução (Painel de Tradução → Falhas).