Documentos

Projetado principalmente para documentação em markdown, MDX e .astro gerenciada por meio de blocos de configuração docs[]. O campo contentPaths de cada bloco lista os arquivos ou pastas a serem traduzidos.

Em sites Docusaurus, defina também docusaurusCatalogDir para sua pasta de catálogo write-translations (por exemplo, docs-site/i18n/en). Então translate-docs inclui JSON de shell também - navbar, rodapé e strings de tema.

Em sites VitePress, os corpos das páginas usam o mesmo pipeline docs[]. Os rótulos de navegação, barra lateral e rodapé ficam em docsOutput.vitepressThemeCatalog - translate-docs inicializa o catálogo em inglês e o traduz junto com as páginas, sem pipeline separado.

Em sites Nextra, os corpos das páginas usam o mesmo pipeline docs[] com docsOutput.style: "nextra". Os rótulos da barra lateral _meta.ts são coletados e traduzidos automaticamente por translate-docs; as strings do dicionário do tema são traduzidas via docs[].nextraDictionaryPath no mesmo pipeline.

Em sites Fumadocs, os corpos das páginas usam docsOutput.style: "fumadocs" com fumadocsParser "dot" (padrão) ou "dir". Os rótulos da barra lateral meta.json são coletados automaticamente; as substituições de UI são traduzidas via docsOutput.fumadocsUiCatalog.

Em sites Astro Starlight, os corpos das páginas usam docsOutput.style: "astro-starlight" com docsRoot na raiz do seu conteúdo Starlight (geralmente src/content/docs/). translate-docs escreve markdown/MDX localizado em src/content/docs/<locale>/ ao lado da árvore em inglês. O Starlight oferece strings de UI integradas para muitos locais — sem pipeline de catálogo de tema separado; substituições opcionais de UI podem usar jsonPathTemplate em um bloco docs[] para src/content/i18n/en.json.

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[].

Para consistência terminológica entre UI e documentos, defina glossary.uiGlossary para o seu caminho strings.json — translate-docs reutiliza traduções de UI existentes como dicas em prompts de LLM quando termos correspondentes aparecem em um segmento. glossary.userGlossary opcional adiciona substituições CSV para termos de produto (compartilhados com translate-ui e proofread-ui). Gere um CSV inicial com glossary-generate, edite linhas na guia Glossário do Painel de Tradução, ou veja Configuração — glossary e Glossário.

Substituições de modelo por localidade

translate-docs e a etapa de documentos de sync resolvem modelos por local de destino: localeModels(locale) primeiro quando configurado, depois a cadeia global translationModels do provedor. Use isso quando um idioma específico precisar de um modelo diferente da sua lista de fallback padrão - por exemplo, preferindo Gemini para documentação pt-BR quando a cadeia global tem dificuldades com o português. Veja Provedores e modelos 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
Documentos planos (README, changelogs, etc.)	docsOutput.style = "flat" - Layouts de saída, troca de idioma opcional
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 UI/documentos	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 <provider>]

Para sites de documentação Astro Starlight:

ai-i18n-tools init -t ui-starlight [-P <provider>]

Para sites de documentação VitePress:

ai-i18n-tools init -t ui-vitepress [-P <provider>]

Defina 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 <provider>]

Defina 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 <provider>]

Defina 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 <provider>]

Esse modelo habilita apenas a extração da UI. Para a tradução de HTML de página, defina também features.translateDocs e adicione um bloco docs[] (consulte Páginas do site Astro (analisar e substituir)). A configuração examples/astro-website mostra ambos os pipelines juntos.

Edite o ai-i18n-tools.config.json gerado:

• provider e providers — init estrutura um bloco de provedor padrão (openrouter a menos que você passe -P <provider>); configure pelo menos um provedor e defina sua chave de API antes de translate-docs ou sync (Ollama não precisa de chave). Veja Provedor e chave de API e Provedores e modelos LLM.
• sourceLocale - idioma de origem (deve corresponder a defaultLocale em docusaurus.config.js).
• targetLocales - array de códigos de localidade BCP-47 (por exemplo, ["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 tem description opcional, contentPaths (string ou array; arquivo, diretório ou glob), outputDir, docusaurusCatalogDir opcional, docsOutput, segmentSplitting opcional, translateFrontmatterFields, protectAttributes, protectKeys, targetLocales, addFrontmatter, etc.
• docs[].description - nota curta opcional para mantenedores. Quando definida, ela aparece no título translate-docs e nos cabeçalhos de seção status.
• docs[].contentPaths - fontes markdown/MDX/.astro (e docusaurusCatalogDir opcional 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" (veja Layouts de saída).
• glossary.uiGlossary - caminho para strings.json para que os segmentos do documento recebam dicas de terminologia do seu catálogo de UI (veja Configuração — glossary).
• glossary.userGlossary - CSV opcional para traduções de termos de produto fixos; também usado por pipelines de UI e editável na guia do painel Glossário.

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-docs

Isso 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 de

Para verificar o que precisa ser traduzido:

ai-i18n-tools status

Para 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 do markdown (incluindo ênfases analisadas a partir do documento). Parágrafos que acumulam 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 única frase longa são frágeis: alguns idiomas exigem ordem de palavras diferente, o que pode alterar como ** e ` se alinham após a tradução e acionar erros na CLI como AST mismatch.

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 todos os modelos configurados falharem com um AST mismatch no mesmo segmento, o translate-docs pode dividir automaticamente esse segmento em partes menores (primeiro o ponto médio da lista, depois itens individuais da lista ou trechos menores de parágrafo), tentar novamente cada parte a partir do primeiro modelo e reunir o resultado sob a chave original do cache do segmento. Isso está ativado por padrão (segmentSplitting.qualityRetrySplit); defina como false para interromper após esgotar os modelos. O resumo da execução relata Quality split retries quando esse recurso de contingência é acionado.

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).