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:
| Etapa | Comando | O que ele faz |
|---|---|---|
| 1 | extract → translate-ui | Escanear fontes da UI → atualizar strings.json → preencher JSON de localidade plana (de.json, …) |
| 2 | translate-svg (opcional) | Traduzir texto SVG em config.svg |
| 3 | translate-docs | Traduzir páginas markdown, MDX, .astro; JSON de catálogo Docusaurus; _meta / dicionário .ts Nextra; catálogo de temas VitePress |
| 4 | translate-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
| Camada | Pasta | Função |
|---|---|---|
| Entrada | src/cli/ | Comandos CLI: init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, … |
| Pipelines | src/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 | |
| Compartilhado | src/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 aplicativo | src/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
| Pipeline | Seção | Entrada → saída |
|---|---|---|
| Strings da UI | Internos das strings da UI | Arquivos de origem → strings.json → {locale}.json plano |
| Documentos | Internos dos documentos | Markdown / MDX / .astro / Docusaurus JSON → arquivos por localidade em docs[].outputDir |
| Pacotes JSON | Internos do JSON | JSON aninhado em json[] → arquivos JSON por localidade |
| SVG | Internos dos documentos — extratores | Arquivos SVG em config.svg → cópias SVG traduzidas |
Detalhes internos das strings da UI
| Etapa | Componente | Resultado |
|---|---|---|
| 1 | Arquivos de origem (JS/TS; .astro / .html opcionais) | Arquivos em disco |
| 2 | UIStringExtractor (Babel via ui-string-babel.ts) | Segmentos indexados por hash MD5 |
| 3 | strings.json | Catálogo mestre: { hash: { source, translated, models?, locations? } } |
| 4 | LlmClient.translateUIBatch() | Array JSON de strings de origem → traduções (+ ID do modelo por lote) |
| 5 | de.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:
{
"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):
{
"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
localeDisplayNamesouui-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
| Etapa | Componente | Resultado |
|---|---|---|
| 1 | Arquivos Markdown / MDX / JSON / .astro (translate-docs) | Arquivos de origem |
| 2 | MarkdownExtractor / JsonExtractor / AstroTemplateExtractor | segments[] — segmentos tipados com hash + conteúdo |
| 3 | PlaceholderHandler | Texto protegido — HTML, advertências, âncoras, MDX, URLs, código inline, ênfase mascarada como tokens |
| 4 | splitTranslatableIntoBatches | batches[] — agrupado por contagem + limite de caracteres |
| 5 | Pesquisa TranslationCache | Cache hit → pular; miss → LlmClient.translateDocumentBatch |
| 6 | PlaceholderHandler.restoreAfterTranslation | Texto final — placeholders restaurados |
| 7 | resolveDocumentationOutputPath | Arquivo 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,ide outras chaves de roteamento permanecem estáveis). Blocosexport ...de nível superior (por exemplo, definições de componentes React) são classificados como segmentosothernão traduzíveis, junto com o tratamento existente deimport .... 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-docsviatranslateAstroFileemdoc-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 det('…'). 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 portranslate-svgpara arquivos emconfig.svg, não portranslate-docs).html-i18n-marks.ts- um scanner focado de tags HTML usado porextractpara fontes.html/.htme pelo comandomark-html.collectHtmlI18nStrings/collectHtmlI18nLocationsleem atributos de marcadordata-i18n*(marcador simples →textContent/title/placeholderdo elemento; marcador com valor → o valor), emarkHtmlContentinsere marcadores simples em texto folha / título / elementos de placeholder (idempotente, respeitadata-i18n-ignore, pula elementos parecidos com código e de conteúdo misto). O helper compartilhadonormalizeI18nTextmanté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/):
| Camada | Mecanismo | Saída |
|---|---|---|
| HTML do modelo | AstroTemplateExtractor + translate-docs | .astro por localidade em docs[].outputDir |
Frontmatter / t('…') | ui-string-babel.ts + extract + translate-ui | public/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):
- 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-groupou::: tipno 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. - 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. - 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). - 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. - Âncoras de documento (HTML
<a id="…">,{#…}remanescente do Docusaurus no meio do cabeçalho) - preservadas literalmente. - 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 emdocs[].protectAttributes;label:dentro de literais de objeto<Tabs values={[ { label: '…' } ]}>(que podem ser ignorados viadocs[].protectKeys) e<TabItem value="…">(quando não existe um atributolabel, ignorando valores em minúsculas do tipo slug) também são extraídos. Anexados ao segmento como linhas||JXA_N: …||, mesclados de volta porrestoreMdx. - Expressões entre chaves do MDX (
{frontMatter.title},style={{…}}) - correspondência ciente da profundidade, substituídas por{{MDX_N}}.
- Comentários MDX (
- URLs do Markdown (
](url),src="…") - restaurados a partir de um mapa após a tradução. - Trechos de código em linha (
`code`) e código em linha envolto em negrito (**code**) - preservados. - Ê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_atnulo / caminho de arquivo vazio); - poda chaves
file_trackingquando 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,targetLocalesraiz e qualquerdocs[]/json[]targetLocalespor bloco; somente SQLite — usepurge-localepara 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: emdocsRoot, as saídas usam{outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}; caminhos fora dedocsRootvoltam para o layout aninhado. Aliases:docusaurus(padrãolocaleSubpath= caminho do plugin Docusaurus),astro-starlight(padrão vaziolocaleSubpath),vitepress(o mesmo quedoc-systemcomlocaleSubpathvazio; preserva o uso de maiúsculas e minúsculas da pasta BCP-47). - Estilo
flat:{outputDir}/{stem}.{locale}{extension}. QuandoflatPreserveRelativeDirétrue, os subdiretórios de origem são mantidos emoutputDir. - 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. linkRewriteDocsRootajuda 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.
Reescrita plana de links
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
| Etapa | Componente | Resultado |
|---|---|---|
| 1 | json[].contentPaths | Arquivos resolvidos (arquivo, diretório ou glob) |
| 2 | NestedJsonExtractor | Folhas de string selecionadas por keyPolicy (caminhos de ponto + minimatch) |
| 3 | PlaceholderHandler + lote + TranslationCache | Cache hit → pular; miss → LlmClient.translateDocumentBatch (SQLite compartilhado) |
| 4 | NestedJsonExtractor.reassemble | Arquivo 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,denylistouboth) filtra caminhos com minimatch na notação de ponto (nomes simples comoslugcorrespondem ao segmento de chave final).- O rastreamento de arquivos de cache usa
json-block:{blockIndex}:{projectRelPath}emfile_tracking(o mesmocacheDirque documentos e SVG). - Não para catálogos
write-translationsdo Docusaurus (formato{ message, description }) — estes usam Documentos (docs[].docusaurusCatalogDir+JsonExtractordentro detranslate-docs). - Não para strings da UI
t()— strings da UI (strings.json+ pacotes planos). - CLI:
translate-json; orquestração emsrc/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, depoisuiModels(somente pipelines de UI), depoistranslationModels. A tradução de documentos, JSON e SVG cria um cliente por localidade com a cadeia não-UI. O comandobench-modelsem vez disso constrói um cliente de modelo único por ID configurado (união detranslationModels,uiModelselocaleModels;translationModels: [id], sem fallback) para que possa cronometrar e precificar cada modelo independentemente. - Tempo limite da requisição:
requestTimeout(segundos) ourequestTimeoutMsno provedor ativo, caso contrário, as mesmas chaves no topo da configuração (padrão 120 segundos), aborta cada requisição viaAbortSignal.timeout. O mesmo valor se aplica aGET /modelsquando a CLI carrega a lista de modelos de um provedor paracheck-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
openrouterestá ativo): roteamento de throughput via o campo de requisiçãoprovidere os cabeçalhosHTTP-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 paracheaper_inference.billing.billed_cost_usd). Quando o provedor omite esse valor, o custo em USD é calculado a partir deproviders.<name>.modelPricing, depois o padrãopricingde todo o provedor, depois o preço de lista de entrada e saída do models.dev, e armazenado na linhaapi_calls. Um custo relatado pelo provedor (incluindo0) 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
debugTrafficFilePathestiver definido, anexa JSON de requisição e resposta a um arquivo (programático). A CLI--debug-failedescreve arquivosFAILED-TRANSLATIONemcacheDircom 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):
- Leia e analise
ai-i18n-tools.config.json(JSON). mergeWithDefaults- mescla profunda comdefaultI18nConfigPartial, e mescla quaisquer entradasdocs[].sourceFilesemcontentPaths.expandTargetLocalesFileReferenceInRawInput- coercetargetLocalespara um array e rejeite entradas semelhantes a caminhos (devem ser códigos BCP-47, não um caminho paraui-languages.json);languagesManifestPathé padrão para{ui.flatOutputDir}/ui-languages.jsondurantemergeWithDefaults.expandDocumentationTargetLocalesInRawInput- mesmo para cada entradadocs[].targetLocales.expandJsonTargetLocalesInRawInput- o mesmo para cada entradajson[].targetLocales.parseI18nConfig- validação Zod +validateI18nBusinessRules.applyProviderOverrideToRawInput- quando-P/--provideré passado na CLI.applyEnvOverrides- aplicaOPENROUTER_BASE_URL,OLLAMA_BASE_URL,I18N_SOURCE_LOCALEeI18N_TARGET_LOCALESquando definidos (as chaves de API são resolvidas separadamente por provedor dentro deLlmClient).augmentConfigWithUiLanguagesMaster- anexa nomes de exibição de manifesto do catálogo mestre empacotado.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 (
resolveUiLocaleemsrc/core/ui-locale.ts): seleciona a localidade da IU de-L/--ui-lang>AI_I18N_LANG> configuraçãouiLanguage> 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 queuiLanguagese aplique (o sinalizador e a variável de ambiente ainda prevalecem). - Tempo de execução (
src/i18n/index.ts): umt(source, vars)mínimo com interpolação{{name}}, indexado pela string de origem em inglês em relação a pacotes planos por localidade emsrc/i18n/locales/<code>.json(copiado paradist/i18n/localesna 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-i18nretornando{ locale, dir, bundle }para a localidade da IU resolvida; o frontend define<html lang>/dire localiza a marcação estática via atributosdata-i18n*. - Dogfooding: os pacotes são produzidos por
pnpm i18n:self(sync-ui --ui-block src/i18n/strings.json), que extrai e traduz o blocouida CLI e do painel emai-i18n-tools.config.json. As chaves do catálogo vêm de chamadast()emsrc/cli/esrc/i18n/, além dos marcadoresdata-i18n*do painel emsrc/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:
{
"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:
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:
{
"docs": [
{
"docsOutput": {
"pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
}
}
]
}Árvore de origem
Layout completo de src/ (referência em nível de arquivo)
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