Skip to content

Arquitetura ​

Visão geral da arquitetura ​

A base de código está organizada em quatro camadas. Use esta seção para o modelo mental; abra a árvore de origem quando precisar de detalhes em nível de arquivo.

Como uma execução de sync se encaixa ​

sync (e os comandos de tradução individuais) executam recursos habilitados em ordem:

EtapaComandoO que ele faz
1extract → translate-uiEscanear fontes da UI → atualizar strings.json → preencher JSON de localidade plana (de.json, …)
2translate-svg (opcional)Traduzir texto SVG em config.svg
3translate-docsTraduzir páginas markdown, MDX, .astro; JSON de catálogo Docusaurus; _meta / dicionário .ts Nextra; catálogo de temas VitePress
4translate-json (opcional)Traduzir folhas JSON aninhadas em json[]

Todo pipeline segue o mesmo loop principal: extrair segmentos → proteger sintaxe → agrupar → pesquisa de cache ou chamada LLM → gravar saída. Serviços compartilhados no meio — configuração, placeholders, cache, glossário, LlmClient — são descritos em Infraestrutura compartilhada.

Mapa de módulos ​

CamadaPastaFunção
Entradasrc/cli/Comandos CLI: init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, …
Pipelinessrc/extractors/Extração de segmentos de JS/TS, marcadores HTML, markdown, JSON, SVG, .astro
src/processors/Proteção de placeholder, agrupamento, validação, reescrita de link
Compartilhadosrc/core/Configuração, tipos, cache SQLite, prompts, caminhos de saída, utilitários de localidade
src/api/LlmClient — cliente de chat agnóstico de provedor (Vercel AI SDK) com fallback de modelo
src/glossary/Carregamento de glossário, dicas de termos e arquivos opcionais de contexto de projeto para prompts
src/utils/Logger, hashing, analisador de ignorados, tabelas de largura de exibição, carregador .env
Tempo de execução do seu aplicativosrc/runtime/Ajudantes i18next e utilitários de exibição — exportados como 'ai-i18n-tools/runtime' (Ajudantes de tempo de execução)
IU da Ferramenta (dogfooding)src/i18n/, src/dashboard-app/, src/server/Localiza a CLI e o Painel de Tradução deste pacote — separadamente do conteúdo do seu projeto (Autolocalização)

Tudo o que se destina ao uso programático é reexportado de src/index.ts (API Programática).

Resumos do pipeline ​

PipelineSeçãoEntrada → saída
Strings da UIInternos das strings da UIArquivos de origem → strings.json → {locale}.json plano
DocumentosInternos dos documentosMarkdown / MDX / .astro / Docusaurus JSON → arquivos por localidade em docs[].outputDir
Pacotes JSONInternos do JSONJSON aninhado em json[] → arquivos JSON por localidade
SVGInternos dos documentos — extratoresArquivos SVG em config.svg → cópias SVG traduzidas

Detalhes internos das strings da UI ​

EtapaComponenteResultado
1Arquivos de origem (JS/TS; .astro / .html opcionais)Arquivos em disco
2UIStringExtractor (Babel via ui-string-babel.ts)Segmentos indexados por hash MD5
3strings.jsonCatálogo mestre: { hash: { source, translated, models?, locations? } }
4LlmClient.translateUIBatch()Array JSON de strings de origem → traduções (+ ID do modelo por lote)
5de.json, pt-BR.json, …Mapas planos: string de origem → tradução (sem metadados do modelo)

UIStringExtractor ​

extractUiCallsFromFileContent em ui-string-babel.ts encontra chamadas de t("literal") e i18n.t("literal"). Arquivos JS e TS são analisados com @babel/parser (código-fonte do módulo, TypeScript e JSX). Para fontes .astro (quando listados em ui.uiExtractor.extensions), a mesma função analisa o frontmatter e os blocos de {expression} de template e aplica as mesmas regras de funcNames. Nomes de função e extensões de arquivo são configuráveis via ui.uiExtractor (ui.reactExtractor é um alias suportado). extract também mescla entradas extras no mesmo catálogo: o package.json description do projeto quando includePackageDescription está habilitado (padrão), e cada englishName do catálogo mestre de ui-languages empacotado (construído a partir de sourceLocale + targetLocales) quando includeUiLanguageEnglishNames é true (strings já encontradas na fonte mantêm precedência; não lê languagesManifestPath). extract também regenera ui-languages.json em languagesManifestPath. Os hashes de segmento são os primeiros 8 caracteres hexadecimais MD5 da string de origem aparada — estes se tornam as chaves em strings.json.

Para fontes .html / .htm (quando listados em ui.uiExtractor.extensions), extract em vez disso roteia o arquivo através de html-i18n-marks.ts, que escaneia os atributos de marcador data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label (configuráveis via ui.uiExtractor.htmlI18nAttributes). Um marcador simples obtém seu texto-fonte do próprio textContent ou atributo do elemento; um marcador com valor (data-i18n="Key") usa o valor. data-i18n-locale-src e data-i18n-locale-href são reservados para o tempo de execução do navegador e nunca são extraídos. O mesmo módulo controla o comando mark-html, que insere os marcadores simples automaticamente (incluindo alt e aria-label) e nunca insere os marcadores de URL de localidade. Arquivos HTML nunca chegam à passagem do Babel. HTML de localidade gerado sob um outputDir de documentação é excluído desta varredura.

Sites Astro SSG simples podem dispensar o i18next: carregue {locale}.json plano em tempo de build e resolva t('source text') pela chave do texto de origem. O idioma de origem é sourceLocale e pode ser qualquer idioma (consulte examples/astro-website/src/i18n/t.ts e Strings de UI — site do Astro).

Aplicativos HTML simples seguem o mesmo modelo de catálogo com atributos de marcador em vez de chamadas t() — veja Marcação de HTML para tradução. O script pronto para uso é ai-i18n-tools/html-runtime/i18n.js.

HTML estático que deve se tornar um arquivo por localidade é um pipeline de documentos (HtmlTemplateExtractor dentro de translate-docs), não este catálogo. Consulte Páginas HTML.

strings.json ​

O catálogo mestre tem a seguinte estrutura:

json
{
  "a1b2c3d4": {
    "source": "The English string",
    "translated": {
      "de": "Der deutsche Text",
      "pt-BR": "O texto em português"
    },
    "models": {
      "de": "anthropic/claude-3.5-haiku",
      "pt-BR": "openai/gpt-4o"
    },
    "locations": [{ "file": "src/app/page.tsx", "line": 51 }]
  }
}

models (opcional) — por locale, qual modelo produziu essa tradução após a última execução bem-sucedida de translate-ui para esse locale (ou user-edited se o texto foi salvo do Translation Dashboard). locations (opcional) — onde extract encontrou a string (scanner + linha de descrição do pacote; strings englishName embutidas-master podem omitir locations).

extract adiciona novas chaves e preserva os dados existentes translated / models para chaves ainda presentes na varredura (literais do scanner, descrição opcional, englishName embutida-master opcional). translate-ui preenche entradas translated faltantes, atualiza models para os locales que traduz, e escreve arquivos de locale planos.

ui-languages.json manifesto — array JSON de { code, label, englishName, direction } (BCP-47 code, UI label, referência englishName, "ltr" ou "rtl"). Use generate-ui-languages ou extract para construir um arquivo de projeto a partir de sourceLocale + targetLocales e do master data/ui-languages-complete.json embutido.

Arquivos de localidade planos ​

Cada localidade de destino recebe um arquivo JSON plano (de.json) mapeando string de origem → tradução (sem campo models):

json
{
  "The English string": "Der deutsche Text",
  "Save": "Speichern"
}

O i18next carrega esses arquivos como pacotes de recursos e procura traduções pela string de origem (modelo de chave como padrão).

Solicitações de tradução de interface ​

buildUIPromptMessages constrói mensagens de sistema e do usuário que:

  • Identifique os idiomas de origem e de destino (pelo nome de exibição de localeDisplayNames ou ui-languages.json).
  • Preponha uma diretiva de script quando o local de destino tiver um sistema de escrita esperado (script BCP-47 explícito ou um padrão de idioma como hi → Devanagari, ar → Árabe, ja → Kana/Kanji japonês).
  • Envie um array JSON de strings e solicite um array JSON de traduções em troca.
  • Inclua dicas de glossário quando disponíveis.

LlmClient.translateUIBatch tenta cada modelo em ordem, recorrendo a erros de análise, rede ou script incorreto (incluindo fallback romanizado/latino para localidades de script nativo). A CLI constrói essa lista por localidade de destino a partir de localeModels, uiModels opcional e translationModels (consulte Modelos de IA).


Detalhes internos dos documentos ​

EtapaComponenteResultado
1Arquivos Markdown / MDX / JSON / .astro (translate-docs)Arquivos de origem
2MarkdownExtractor / JsonExtractor / AstroTemplateExtractorsegments[] — segmentos tipados com hash + conteúdo
3PlaceholderHandlerTexto protegido — HTML, advertências, âncoras, MDX, URLs, código inline, ênfase mascarada como tokens
4splitTranslatableIntoBatchesbatches[] — agrupado por contagem + limite de caracteres
5Pesquisa TranslationCacheCache hit → pular; miss → LlmClient.translateDocumentBatch
6PlaceholderHandler.restoreAfterTranslationTexto final — placeholders restaurados
7resolveDocumentationOutputPathArquivo de saída — layout Docusaurus ou layout plano

Extratores ​

Todos os extratores estendem BaseExtractor e implementam extract(content, filepath): Segment[].

  • MarkdownExtractor - divide markdown em segmentos tipados: frontmatter, heading, paragraph, code, admonition. O frontmatter YAML é classificado como não traduzível (slug, id e outras chaves de roteamento permanecem estáveis). Blocos export ... de nível superior (por exemplo, definições de componentes React) são classificados como segmentos other não traduzíveis, junto com o tratamento existente de import .... Blocos multilinha que começam com uma tag JSX com inicial maiúscula (por exemplo, um bloco <Tabs>) são classificados como parágrafos traduzíveis. Segmentos não traduzíveis (blocos de código, HTML bruto) são preservados literalmente.
  • AstroTemplateExtractor - análise e substituição para páginas de marketing .astro (translate-docs via translateAstroFile em doc-translate.ts). Extrai nós de texto HTML visíveis ao usuário e atributos traduzíveis (alt, title, aria-label, placeholder), além de literais de string dentro de blocos de template {expression} quando visíveis ao usuário. Ignora frontmatter TypeScript, <script>, <style>, valores protegidos de atributos/chaves e literais dentro de t('…'). A remontagem ajusta imports relativos quando os caminhos de saída estão em níveis mais profundos (por exemplo, src/pages/de/index.astro). Consulte Páginas do site do Astro.
  • JsonExtractor - extrai valores de string de arquivos JSON de rótulos do Docusaurus (catálogos de UI do Docusaurus, não o corpo MDX).
  • SvgExtractor - extrai conteúdo de <text>, <title> e <desc> de SVG (usado por translate-svg para arquivos em config.svg, não por translate-docs).
  • html-i18n-marks.ts - um scanner focado de tags HTML usado por extract para fontes .html / .htm e pelo comando mark-html. collectHtmlI18nStrings / collectHtmlI18nLocations leem atributos de marcador data-i18n* (marcador simples → textContent / title / placeholder do elemento; marcador com valor → o valor), e markHtmlContent insere marcadores simples em texto folha / título / elementos de placeholder (idempotente, respeita data-i18n-ignore, pula elementos parecidos com código e de conteúdo misto). O helper compartilhado normalizeI18nText mantém as chaves de tempo de compilação idênticas ao runtime do navegador.

Sites híbridos Astro (UI + HTML de página) ​

Aplicativos Astro simples geralmente habilitam ambas as strings da UI e os documentos em uma única configuração (referência: examples/astro-website/):

CamadaMecanismoSaída
HTML do modeloAstroTemplateExtractor + translate-docs.astro por localidade em docs[].outputDir
Frontmatter / t('…')ui-string-babel.ts + extract + translate-uipublic/locales/{locale}.json plano (string no idioma de origem como chave; sourceLocale pode ser qualquer idioma)

O comando sync executa as etapas habilitadas em ordem: extrair e depois traduzir-ui (quando features.translateUIStrings) → traduzir-svg opcional → traduzir-docs → traduzir-json opcional (a menos que ignorado com --no-ui, --no-svg, --no-docs ou --no-json). O modelo de inicialização ui-astro-website gera apenas strings da UI; adicione docs[] e features.translateDocs para HTML da página.

Inserção de âncoras de título (write-heading-ids CLI) ​

O comando write-heading-ids é um pré-processador local, sem uso de LLM, para arquivos markdown de documentação. Implementação: src/cli/write-heading-ids.ts coordena a descoberta de arquivos; src/markdown/write-heading-ids-core.ts analisa as linhas e insere âncoras.

É necessário um arquivo de configuração válido com pelo menos um bloco docs[]. Para cada bloco, ele coleta arquivos .md / .mdx em contentPaths, aplica as regras .translate-ignore do projeto (mesma ideia da tradução de documentos) e, opcionalmente, restringe a uma subárvore com --path / --file. Cada arquivo é transformado com applyHeadingAnchorsToMarkdown: para cada cabeçalho ATX simples (# … a ###### …) fora dos blocos de código cercados, os IDs de cabeçalho existentes de qualquer forma são substituídos pelo estilo selecionado. Os estilos HTML escrevem <a id="slug"></a> na linha acima de um cabeçalho sem sufixo; --slug-style mdx-comment escreve {/* #slug */} na linha do cabeçalho (e remove uma âncora HTML anterior). Os slugs sempre vêm do texto do cabeçalho atual. --remove remove âncoras HTML, sufixos clássicos {#id} e IDs de comentários MDX sem escrever novos. Os algoritmos de slug correspondem a ecossistemas comuns — github (padrão), bitbucket, gitlab, pymdown (sinalizadores opcionais de normalização Unicode / codificação percentual), azure-devops, mais mdx-comment (slug do github + saída de comentário MDX) — para que os IDs de âncora permaneçam consistentes com as ferramentas existentes (doctoc, PyMdown, Docusaurus, etc.). --dry-run relata edições potenciais sem escrever.

Após a passagem da fonte, o mesmo comando reposiciona esses IDs em inglês no markdown traduzido existente de cada localidade (resolveTranslatedOutputPath). Títulos traduzidos nunca são re-slugged; um {#id} / {/* #id */} no meio do título é movido de volta para o sufixo (ou âncora HTML) que o estilo selecionado espera. Arquivos de localidade ausentes são ignorados.

Este comando não é executado dentro do translate-docs ou do sync; execute-o explicitamente quando desejar IDs de fragmento estáveis nos arquivos de origem antes da tradução ou publicação.

Proteção de espaços reservados ​

Antes da tradução, a sintaxe sensível é substituída por tokens opacos para evitar corrupção pelo LLM, aplicado nesta ordem (a restauração é inversa):

  1. Blocos de código cercados (três ou mais crases ou tis, incluindo uma cerca mais longa que envolve uma mais curta) - a cerca inteira, incluindo a string de informação, é substituída por {{CDF_N}} e mantida em ordem com os outros tokens estruturais. Isso mantém as amostras dentro de contêineres como ::: code-group ou ::: tip no lugar. As strings de informação da cerca (rótulos de aba do VitePress) permanecem no idioma de origem. Um abridor não fechado é deixado como texto para que um fechador de contêiner posterior não seja absorvido.
  2. Sufixos de ID de cabeçalho ({#id} clássico / {/* #id */} MDX no final de um cabeçalho ATX) — removidos inteiramente da linha e não enviados para o modelo. Após a restauração, eles são fixados de volta no final do cabeçalho correspondente para que o Docusaurus ainda veja um ID válido. Comentários no meio do cabeçalho permanecem no texto e são tratados pelas camadas posteriores de MDX / {#…}. Cabeçalhos dentro de uma cerca mascarada não são removidos.
  3. Tags e comentários HTML (<strong>, <!-- ... -->, etc.) - tags HTML em minúsculas de uma lista de permissões conhecida são substituídas por tokens {{HTM_N}}. Tags JSX em maiúsculas (<Highlight>, <Tabs>, </Tab>) são tratadas separadamente pela camada MDX (passo 6).
  4. Marcadores de admonition (:::note, :::) - apenas o prefixo da diretiva na linha de abertura é substituído por {{ADM_OPEN_N}}; qualquer título na mesma linha é deixado para o modelo traduzir. Restaurado com o texto original exato.
  5. Âncoras de documento (HTML <a id="…">, {#…} remanescente do Docusaurus no meio do cabeçalho) - preservadas literalmente.
  6. Construções exclusivas do MDX (src/processors/mdx-placeholders.ts):
    • Comentários MDX ({/* … */}, incluindo um {/* #my-id */} no meio do cabeçalho que não era um sufixo de final de linha) substituídos por {{MDX_N}}.
    • Tags JSX em maiúsculas (<Highlight>, <Tabs>, <TabItem>, <TOCInline />, </Highlight>) - preservadas como {{MDX_N}} com atributos de string traduzíveis (label, tooltip, aria-label) reescritos como {{JXA_N}} dentro da tag, a menos que o nome do atributo apareça em docs[].protectAttributes; label: dentro de literais de objeto <Tabs values={[ { label: '…' } ]}> (que podem ser ignorados via docs[].protectKeys) e <TabItem value="…"> (quando não existe um atributo label, ignorando valores em minúsculas do tipo slug) também são extraídos. Anexados ao segmento como linhas ||JXA_N: …||, mesclados de volta por restoreMdx.
    • Expressões entre chaves do MDX ({frontMatter.title}, style={{…}}) - correspondência ciente da profundidade, substituídas por {{MDX_N}}.
  7. URLs do Markdown (](url), src="…") - restaurados a partir de um mapa após a tradução.
  8. Trechos de código em linha (`code`) e código em linha envolto em negrito (**code**) - preservados.
  9. Ênfase do Markdown (opcional, ativado automaticamente para localidades CJK/RTL) - delimitadores de ênfase mascarados.

Depois que o modelo retorna, o translate-docs restaura os mapas e valida o segmento: o mesmo multiconjunto de tokens de chaves duplas deve estar presente, os tokens estruturais ({{HTM_N}}, marcadores de admonition, {{CDF_N}}) devem manter sua subsequência ordenada (tokens de conteúdo como {{ILC_N}} / {{URL_N}} / {{SE}} podem se mover com a ordem das palavras), os tipos de tag HTML restaurados devem corresponder ao código-fonte não protegido, e qualquer identificador de chaves duplas remanescente já deve ter existido no código-fonte (para que tokens inventados falhem). O prompt do documento também pede aos modelos para copiar cada token uma vez, manter a ordem dos tokens estruturais e não inventar novos invólucros de chaves duplas; as verificações mecânicas permanecem autoritativas.

A proteção de atributos/chaves compartilhados para modelos Astro e MDX JSX é implementada em src/processors/expression-attribute-protection.ts e controlada por bloco por docs[].protectAttributes e docs[].protectKeys (consulte protectAttributes / protectKeys).

Cache (TranslationCache) ​

O banco de dados SQLite (via node:sqlite) armazena linhas indexadas por (source_hash, locale) com translated_text, model, filepath, last_hit_at e campos relacionados. O hash corresponde aos primeiros 16 caracteres hexadecimais SHA-256 do conteúdo normalizado (espaços em branco reduzidos).

Em cada execução, os segmentos são pesquisados por hash × localidade. Apenas as falhas de cache vão para o LLM. Após a tradução, last_hit_at é redefinido para as linhas de segmento no escopo de tradução atual que não foram acessadas. Acertos de cache bem-sucedidos durante a tradução de documentos limpam linhas translation_failures obsoletas para esse segmento.

cleanup executa sync --force-update primeiro, depois:

  • remove linhas de segmento obsoletas (last_hit_at nulo / caminho de arquivo vazio);
  • poda chaves file_tracking quando o caminho de origem resolvido está ausente no disco (doc-block:…, json-block:…, svg-files:…, etc.);
  • remove linhas de tradução cujo caminho de arquivo de metadados aponta para um arquivo ausente;
  • poda linhas translation_failures órfãs;
  • poda linhas markdown_source_issues órfãs cujo caminho de origem resolvido está ausente no disco;
  • descarta linhas de cache para localidades ausentes da configuração (sourceLocale, targetLocales raiz e qualquer docs[] / json[] targetLocales por bloco; somente SQLite — use purge-locale para excluir arquivos gerados).

Ele não faz backup de cache.db a menos que --backup <path> seja passado, o que primeiro grava um backup nesse caminho.

As chamadas de modelo faturadas (traduções aceitas e retentativas descartadas) são armazenadas em api_calls. Após um comando que registrou chamadas, as linhas de detalhes com mais de sete dias corridos em UTC são consolidadas nas api_totals mensais. usage e a visualização Uso e custos do painel combinam ambas as tabelas. Consulte Uso e custos.

Notas de glossário Context e glossary.contextFiles são impressas digitalmente (prompt_context_hash) e injetadas na UI, documentos, JSON, SVG e prompts de revisão. Alterar essa orientação invalida segmentos em cache correspondentes e linhas de rastreamento de arquivos na próxima execução. Linhas de cache do painel user-edited são mantidas. Alterar apenas uma tradução de glossário preferencial em uma linha não forçada mantém o cache existente até --force / --force-update. Uma linha Force perde o cache apenas para segmentos cuja origem contém esse termo quando o texto armazenado ainda não inclui a tradução forçada, e a omissão de arquivo inalterado é recusada para um arquivo cuja saída ainda não o inclui. Deixe Context vazio nessa linha; uma nota de Contexto ainda atualiza todo o local. O Markdown também rejeita um segmento traduzido que omite um rótulo de UI citado de duas a cinco palavras (chave de catálogo ou um prefixo em forma de rótulo pré-definido). Uma citação é negrito, código inline, um cabeçalho ou uma linha que contém apenas esse rótulo. O uso de maiúsculas e minúsculas (title case) dentro de uma frase é uma dica para que a tradução possa ser flexionada (o Hindi Cursor account pode se tornar कर्सर खाते em vez da forma de dicionário कर्सर खाता). Um rótulo de palavra única como Sign in permanece uma dica. A verificação ignora a capitalização na tradução, portanto, um rótulo em minúsculas na frase ainda conta quando a origem o cita. A prosa comum que usa as mesmas palavras pode flexioná-las. Um prefixo pré-definido deve ser um rótulo capitalizado cuja tradução compartilhada é uma frase curta sem um placeholder; raízes de frases não são pré-definidas. Essa verificação tenta novamente o próximo modelo e não divide o segmento.

O comando translate-docs também usa rastreamento de arquivos para que fontes inalteradas com saídas existentes e atualizadas possam pular o trabalho inteiramente. --check-cache reabre localidades com um sistema de escrita esperado para que os segmentos em cache sejam revalidados; --force-update reexecuta o processamento de arquivos para cada localidade enquanto ainda usa o cache de segmentos; --force limpa o rastreamento de arquivos e ignora as leituras do cache de segmentos para tradução de API. Quando os modelos tentados para um segmento markdown falham na validação AST, translate-docs pode dividir progressivamente o segmento e tentar novamente partes menores (docs[].segmentSplitting.qualityRetrySplit, ativado por padrão). O mesmo erro de qualidade por três vezes encerra essa lista de modelos mais cedo. Consulte Documentos — comportamento e sinalizadores de cache para a tabela completa de sinalizadores.

Formato de prompt em lote: translate-docs --prompt-format seleciona XML (<seg> / <t>) ou formatos de array/objeto JSON apenas para LlmClient.translateDocumentBatch; extração, placeholders e validação permanecem inalterados. Consulte Formato de prompt em lote.

Resolução de caminho de saída ​

resolveDocumentationOutputPath(config, cwd, locale, relPath, kind) mapeia um caminho relativo à fonte para o caminho de saída:

  • Estilo nested (padrão): {outputDir}/{locale}/{relPath} para markdown.
  • Estilo doc-system: em docsRoot, as saídas usam {outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}; caminhos fora de docsRoot voltam para o layout aninhado. Aliases: docusaurus (padrão localeSubpath = caminho do plugin Docusaurus), astro-starlight (padrão vazio localeSubpath), vitepress (o mesmo que doc-system com localeSubpath vazio; preserva o uso de maiúsculas e minúsculas da pasta BCP-47).
  • Estilo flat: {outputDir}/{stem}.{locale}{extension}. Quando flatPreserveRelativeDir é true, os subdiretórios de origem são mantidos em outputDir.
  • Personalizado pathTemplate: qualquer layout markdown usando {outputDir}, {locale}, {LOCALE}, {relPath}, {stem}, {basename}, {extension}, {docsRoot}, {relativeToDocsRoot}.
  • Personalizado jsonPathTemplate: layout personalizado separado para arquivos de rótulos JSON, usando os mesmos espaços reservados.
  • linkRewriteDocsRoot ajuda o reescritor de links planos a calcular os prefixos corretos quando a saída traduzida está localizada em outro lugar além da raiz padrão do projeto.

Quando docsOutput.style === "flat", os arquivos markdown traduzidos são colocados ao lado da fonte com sufixos de localidade. Links relativos entre páginas são reescritos para que [Guide](./guide.md) em readme.de.md aponte para guide.de.md. Controlado por rewriteRelativeLinks (ativado automaticamente para estilo plano sem um pathTemplate personalizado). A mesma passagem adiciona um prefixo de profundidade por arquivo a URLs de ativos não-markdown antes que postProcessing.regexAdjustments seja executado — veja Flat link rewriter.


Detalhes internos do JSON ​

EtapaComponenteResultado
1json[].contentPathsArquivos resolvidos (arquivo, diretório ou glob)
2NestedJsonExtractorFolhas de string selecionadas por keyPolicy (caminhos de ponto + minimatch)
3PlaceholderHandler + lote + TranslationCacheCache hit → pular; miss → LlmClient.translateDocumentBatch (SQLite compartilhado)
4NestedJsonExtractor.reassembleArquivo de saída via expandJsonBlockOutputPath(outputPathTemplate)
  • NestedJsonExtractor (src/extractors/nested-json-extractor.ts) percorre JSON aninhado arbitrário e emite um segmento por folha de string traduzível. keyPolicy.mode (allowlist, denylist ou both) filtra caminhos com minimatch na notação de ponto (nomes simples como slug correspondem ao segmento de chave final).
  • O rastreamento de arquivos de cache usa json-block:{blockIndex}:{projectRelPath} em file_tracking (o mesmo cacheDir que documentos e SVG).
  • Não para catálogos write-translations do Docusaurus (formato { message, description }) — estes usam Documentos (docs[].docusaurusCatalogDir + JsonExtractor dentro de translate-docs).
  • Não para strings da UI t() — strings da UI (strings.json + pacotes planos).
  • CLI: translate-json; orquestração em src/cli/translate-json-run.ts. Modelo init: ui-json-bundles.

Infraestrutura compartilhada ​

LlmClient ​

Cliente de chat independente de provedor construído sobre o Vercel AI SDK (ai + @ai-sdk/openai-compatible). Ele resolve o provedor ativo a partir de provider / providers, constrói um cliente compatível com OpenAI (createOpenAICompatible) para o baseUrl + chave de API desse provedor e roteia todas as chamadas através de generateText. OpenRouterClient é mantido como um alias obsoleto. Comportamentos chave:

  • Fallback do modelo: tenta cada modelo na lista resolvida em ordem; retorna em caso de falhas de requisição ou análise. Cada localidade de destino obtém sua própria cadeia resolvida: localeModels(locale) primeiro quando configurado, depois uiModels (somente pipelines de UI), depois translationModels. A tradução de documentos, JSON e SVG cria um cliente por localidade com a cadeia não-UI. O comando bench-models em vez disso constrói um cliente de modelo único por ID configurado (união de translationModels, uiModels e localeModels; translationModels: [id], sem fallback) para que possa cronometrar e precificar cada modelo independentemente.
  • Tempo limite da requisição: requestTimeout (segundos) ou requestTimeoutMs no provedor ativo, caso contrário, as mesmas chaves no topo da configuração (padrão 120 segundos), aborta cada requisição via AbortSignal.timeout. O mesmo valor se aplica a GET /models quando a CLI carrega a lista de modelos de um provedor para check-models (qualquer provedor). O filtro opcional de pré-voo que descarta IDs de modelo desconhecidos é executado apenas quando o provedor ativo é o OpenRouter.
  • Extras do OpenRouter (somente quando openrouter está ativo): roteamento de throughput via o campo de requisição provider e os cabeçalhos HTTP-Referer / X-Title. O uso de tokens é relatado para cada provedor. OpenRouter e Cheaper Inference também retornam um valor faturado em USD (usage.cost; Cheaper Inference retorna para cheaper_inference.billing.billed_cost_usd). Quando o provedor omite esse valor, o custo em USD é calculado a partir de providers.<name>.modelPricing, depois o padrão pricing de todo o provedor, depois o preço de lista de entrada e saída do models.dev, e armazenado na linha api_calls. Um custo relatado pelo provedor (incluindo 0) nunca é substituído. Custo desconhecido permanece não definido. A precificação de uma chamada lê apenas a fatia models.dev de <cacheDir>/benchmark-scores.json; não baixa o languagebench ou o arquivo Arena.
  • Log de tráfego de depuração: se debugTrafficFilePath estiver definido, anexa JSON de requisição e resposta a um arquivo (programático). A CLI --debug-failed escreve arquivos FAILED-TRANSLATION em cacheDir com o prompt do sistema/usuário, a resposta bruta do assistente e erros de validação para tentativas falhas de verificação de tradução de UI, documentos, JSON e SVG. Falhas da API do provedor / corpo vazio são impressas no console em vez de despejar um arquivo somente com o prompt.

suggest-models e a aba Modelos do painel não chamam o LLM. Eles classificam o catálogo de chat do provedor ativo com um índice de qualidade de languagebench ChrF e LMArena Arena Score. O preço é uma taxa combinada de 3:1 USD por 1 milhão de tokens (catálogo, depois models.dev, depois languagebench). --quality ordena por índice; --price percorre a fronteira de Pareto de qualidade-preço. Eles substituem opcionalmente providers.<name>.translationModels. Os agregados ficam em <cacheDir>/benchmark-scores.json. Consulte Modelos de IA e sugerir modelos.

Carregamento de configuração ​

Pipeline loadI18nConfigFromFile(configPath, cwd):

  1. Leia e analise ai-i18n-tools.config.json (JSON).
  2. mergeWithDefaults - mescla profunda com defaultI18nConfigPartial, e mescla quaisquer entradas docs[].sourceFiles em contentPaths.
  3. expandTargetLocalesFileReferenceInRawInput - coerce targetLocales para um array e rejeite entradas semelhantes a caminhos (devem ser códigos BCP-47, não um caminho para ui-languages.json); languagesManifestPath é padrão para {ui.flatOutputDir}/ui-languages.json durante mergeWithDefaults.
  4. expandDocumentationTargetLocalesInRawInput - mesmo para cada entrada docs[].targetLocales.
  5. expandJsonTargetLocalesInRawInput - o mesmo para cada entrada json[].targetLocales.
  6. parseI18nConfig - validação Zod + validateI18nBusinessRules.
  7. applyProviderOverrideToRawInput - quando -P / --provider é passado na CLI.
  8. applyEnvOverrides - aplica OPENROUTER_BASE_URL, OLLAMA_BASE_URL, I18N_SOURCE_LOCALE e I18N_TARGET_LOCALES quando definidos (as chaves de API são resolvidas separadamente por provedor dentro de LlmClient).
  9. augmentConfigWithUiLanguagesMaster - anexa nomes de exibição de manifesto do catálogo mestre empacotado.
  10. assertEffectiveLocalesInUiLanguagesMaster - valida códigos de localidade em relação ao catálogo mestre quando aplicável.

init escreve configurações iniciais de initConfigTemplates: ui-markdown (strings de UI mais um bloco README simples), docs-markdown (somente README e Markdown), ui-docusaurus, ui-starlight, ui-vitepress (documentação do VitePress + vitepressThemeCatalog), ui-nextra (documentação do Nextra + nextraDictionaryPath), ui-astro-website (UI simples do Astro; adicione docs[] para tradução de página .astro), ui-json-bundles (somente JSON json[]), ui-python, ui-python-gettext, ui-python-django e ui-python-flask. --with-readme anexa esse mesmo bloco README a qualquer template que ainda não liste README.md e ativa translateDocs. Consulte Strings de UI — Inicializar, Adicionar i18n à sua documentação README e Markdown e Aplicações Python.

Registrador de eventos (Logger) ​

Logger suporta níveis debug, info, warn, error com saída de cores ANSI. O modo detalhado (-v) habilita debug. Quando logFilePath está definido, as linhas de log também são gravadas nesse arquivo.

Autolocalização (IU da ferramenta) ​

A ferramenta localiza sua própria IU — ajuda da CLI, mensagens de log/resumo/erro de alto tráfego e o Painel de Tradução — separadamente do conteúdo que ela traduz para você.

  • Resolução de localidade (resolveUiLocale em src/core/ui-locale.ts): seleciona a localidade da IU de -L / --ui-lang > AI_I18N_LANG > configuração uiLanguage > localidade do SO host (Intl.DateTimeFormat().resolvedOptions().locale). O candidato é normalizado e comparado com o conjunto de pacotes enviados exatamente ou pela variação mais próxima (por exemplo, pt-PT → pt-BR, en-US → en-GB), recorrendo à localidade de origem (en-GB). A CLI resolve uma vez antes que a ajuda seja construída (verificação de argv pré-análise) e novamente após o carregamento da configuração para que uiLanguage se aplique (o sinalizador e a variável de ambiente ainda prevalecem).
  • Tempo de execução (src/i18n/index.ts): um t(source, vars) mínimo com interpolação {{name}}, indexado pela string de origem em inglês em relação a pacotes planos por localidade em src/i18n/locales/<code>.json (copiado para dist/i18n/locales na compilação). Chaves ou pacotes ausentes retornam o texto de origem. Este é o mesmo modelo de chave como padrão que as strings da IU — não há pesquisa de hash.
  • Painel: o servidor expõe GET /api/ui-i18n retornando { locale, dir, bundle } para a localidade da IU resolvida; o frontend define <html lang> / dir e localiza a marcação estática via atributos data-i18n*.
  • Dogfooding: os pacotes são produzidos por pnpm i18n:self (sync-ui --ui-block src/i18n/strings.json), que extrai e traduz o bloco ui da CLI e do painel em ai-i18n-tools.config.json. As chaves do catálogo vêm de chamadas t() em src/cli/ e src/i18n/, além dos marcadores data-i18n* do painel em src/dashboard-app/index.html.

Pontos de extensão ​

Nomes personalizados de funções (extração da interface) ​

Adicione nomes não padrão de funções de tradução via configuração:

json
{
  "ui": {
    "uiExtractor": {
      "funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
      "extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
      "htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
    }
  }
}

(ui.reactExtractor é um alias totalmente suportado para ui.uiExtractor.)

Adicione .html / .htm a extensions para escanear atributos de marcador HTML durante extract. ui.uiExtractor.htmlI18nAttributes é opcional e usa o padrão ["data-i18n", "data-i18n-title", "data-i18n-placeholder"]; data-i18n mapeia para o textContent do elemento e data-i18n-<attr> mapeia para o valor do atributo (por exemplo, data-i18n-aria-label).

Extratores personalizados ​

Implemente ContentExtractor a partir do pacote:

ts
import { BaseExtractor, type Segment } from 'ai-i18n-tools';

class MyExtractor extends BaseExtractor {
  readonly name = 'my-format';
  canHandle(filepath: string) { return filepath.endsWith('.myext'); }
  extract(content: string, filepath: string): Segment[] { /* … */ }
  reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}

Registre extratores personalizados estendendo as classes de extrator públicas exportadas de 'ai-i18n-tools' (por exemplo, subclasse MarkdownExtractor). A CLI conecta extratores internos internamente; não há importação profunda suportada de doc-translate.ts.

Caminhos de saída personalizados ​

Use docsOutput.pathTemplate para qualquer estrutura de arquivos:

json
{
  "docs": [
    {
      "docsOutput": {
        "pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
      }
    }
  ]
}

Árvore de origem ​

Layout completo de src/ (referência em nível de arquivo)
text
src/
├── index.ts                        Public API re-exports
│
├── cli/
│   ├── index.ts                    CLI entry point (commander)
│   ├── extract-strings.ts          `extract` command implementation
│   ├── mark-html.ts                `mark-html` command (insert bare `data-i18n*` markers into HTML)
│   ├── translate-ui-strings.ts     `translate-ui` command implementation
│   ├── doc-translate.ts            `translate-docs` command (documentation files only)
│   ├── translate-json-run.ts       `translate-json` command (`json[]` nested locale bundles)
│   ├── translate-svg.ts            `translate-svg` command (SVG files from `config.svg`)
│   ├── write-heading-ids.ts        `write-heading-ids` command (markdown heading anchors)
│   ├── bench-models.ts             `bench-models` command (per-model translate latency/token/cost benchmark)
│   ├── helpers.ts                  Shared CLI utilities
│   └── file-utils.ts               File collection helpers
│
├── markdown/
│   └── write-heading-ids-core.ts   Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│   ├── types.ts                    Zod schemas + TypeScript types for all config shapes
│   ├── config.ts                   Config loading, merging, validation, init templates
│   ├── cache.ts                    SQLite translation cache (node:sqlite)
│   ├── prompt-builder.ts           LLM prompt construction for docs and UI strings
│   ├── output-paths.ts             Docusaurus / flat output path resolution
│   ├── ui-languages.ts             ui-languages.json loading and locale resolution
│   ├── ui-locale.ts                Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│   ├── locale-utils.ts             BCP-47 normalisation, locale list parsing, script/Han-variant validation
│   └── errors.ts                   Typed error classes
│
├── extractors/
│   ├── base-extractor.ts           Abstract base class for all extractors
│   ├── ui-string-extractor.ts      JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│   ├── ui-string-babel.ts          Babel `t()` discovery (`extractUiCallsFromFileContent`)
│   ├── ui-string-locations.ts      Source locations for extracted UI strings
│   ├── html-i18n-marks.ts          HTML `data-i18n*` marker scanner + `mark-html` annotator
│   ├── classify-segment.ts         Heuristic segment type classification
│   ├── markdown-extractor.ts       Markdown / MDX segment extraction
│   ├── markdown-segment-split.ts   Optional segment splitting for long markdown blocks
│   ├── frontmatter-fields.ts       Selective YAML front matter field translation
│   ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│   ├── json-extractor.ts           Docusaurus catalog JSON extraction (`translate-docs`)
│   ├── nested-json-extractor.ts    Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│   └── svg-extractor.ts            SVG text extraction
│
├── processors/
│   ├── placeholder-handler.ts      Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│   ├── expression-attribute-protection.ts  Shared protected attribute/key lists (Astro + MDX JSX)
│   ├── url-placeholders.ts         Markdown URL protection/restore
│   ├── admonition-placeholders.ts  Docusaurus admonition protection/restore
│   ├── anchor-placeholders.ts      HTML anchor / heading ID protection/restore
│   ├── html-tag-placeholders.ts    Lowercase HTML tag / comment protection ({{HTM_N}})
│   ├── placeholder-integrity.ts    Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│   ├── mdx-placeholders.ts         MDX comments, JSX tags, brace expressions, JSX attribute extraction
│   ├── batch-processor.ts          Segment → batch grouping (count + char limits)
│   ├── validator.ts                Post-translation structural checks
│   └── flat-link-rewrite.ts        Relative link rewriting for flat output
│
├── api/
│   ├── llm-client.ts               LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│   └── provider-models-catalog.ts  Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│   ├── glossary.ts                 Glossary loading (CSV + auto-build from strings.json)
│   ├── matcher.ts                  Term hint extraction for prompts
│   └── translation-context.ts      contextFiles loader and guidance fingerprints
│
├── runtime/
│   ├── index.ts                    Runtime re-exports
│   ├── template.ts                 interpolateTemplate, flipUiArrowsForRtl
│   ├── ui-language-display.ts      getUILanguageLabel, getUILanguageLabelNative
│   └── i18next-helpers.ts          RTL detection, i18next setup factories
│
├── i18n/                           Self-localisation runtime for the tool's own UI
│   ├── index.ts                    t(source, vars) + bundle/manifest loaders (keyed by English source string)
│   └── locales/                    Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│   ├── index.html                  Translation Dashboard static UI (HTML/CSS/JS)
│   ├── app.js
│   └── styles.css
│
├── server/
│   └── translation-dashboard.ts    Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
    ├── logger.ts                   Leveled logger with ANSI support
    ├── hash.ts                     Segment hash (SHA-256 first 16 hex)
    ├── table.ts                    Display-width aware table rendering (CJK/emoji column alignment)
    ├── load-dotenv.ts              Load `.env` / `.env.local` beside the config when no API key is set
    └── ignore-parser.ts            .translate-ignore file parser

Lançado sob a Licença MIT.