Fluxo de Trabalho de Manutenção de Tradução

Para comandos de documentação geral (build, deploy, screenshots, geração de README), consulte Ferramentas de Documentação.

Visão geral

A documentação utiliza o Docusaurus i18n com o inglês como o locale padrão. A documentação fonte reside em docs/; as traduções são escritas em i18n/{locale}/. Locales suportados: en-GB (padrão), fr, de, es, pt-BR, hi-Latn, zh-Hans.

Tradução por IA para a interface do aplicativo, markdown/JSON do Docusaurus e ativos SVG é gerenciada por ai-i18n-tools a partir da raiz do repositório, configurada em ai-i18n-tools.config.json (não dentro de documentation/). Defina OPENROUTER_API_KEY ao executar comandos de tradução.

Quando a documentação em inglês mudar

1. Edite a fonte em documentation/docs/ (somente em inglês).
2. Strings da interface do Docusaurus (rótulos de tema, barra de navegação, etc.): se necessário, execute pnpm write-translations em documentation/ para que o i18n/en/*.json detecte as novas chaves.
3. IDs de títulos: pnpm write-heading-ids (de documentation/).
4. Traduza a partir da raiz do repositório (ou use os atalhos abaixo a partir de documentation/):
   • pnpm i18n:extract — atualiza src/locales/strings.json a partir de t('…') no aplicativo Next.js.
   • pnpm i18n:translate:docs — traduz markdown/JSON para documentation/i18n/ conforme a configuração.
   • pnpm i18n:translate:svg — traduz SVGs em documentation/static/img conforme configurado.
   • Ou execute tudo: pnpm i18n:translate.
5. Compilação: cd documentation && pnpm build (todas as localidades).

A partir de dentro de documentation/, os mesmos fluxos são conectados como pnpm translate → raiz i18n:translate, além de pnpm translate:docs, translate:ui, translate:svg, translate:status, i18n:extract, i18n:sync.

Glossário

• Terminologia da interface para documentação é definida por glossary.uiGlossary em ai-i18n-tools.config.json, apontando para src/locales/strings.json (o catálogo gerado por pnpm i18n:extract).
• Substituições ficam em documentation/glossary-user.csv (glossary.userGlossary na configuração). Veja a documentação de glossário do ai-i18n-tools para o formato das colunas.
• Gere um modelo CSV: pnpm i18n:glossary-generate (raiz).

Cache

O cache de tradução para o ai-i18n-tools está em .translation-cache/ na raiz do repositório (cacheDir em ai-i18n-tools.config.json). Ele é ignorado pelo git. Use pnpm i18n:status e as opções --force / cache da CLI conforme a documentação do ai-i18n-tools quando precisar de uma atualização completa.

IDs de títulos e âncoras

Use IDs explícitos para que os links permaneçam estáveis entre os idiomas:

## This is a heading \{#this-is-a-heading}

cd documentation
pnpm write-heading-ids

Listas de ignorados

Use .translate-ignore na raiz do repositório (mesma ideia do .gitignore) para caminhos que o tradutor de documentos deve ignorar, caso você adicione um ao seu fluxo de trabalho.

Tema JSON do Docusaurus

pnpm write-translations extrai as strings da interface do Docusaurus para documentation/i18n/en/. A etapa translate-docs do ai-i18n-tools (com markdownOutput.style: "docusaurus") preenche os JSON traduzidos em cada localidade ao lado do markdown, conforme ai-i18n-tools.config.json.

Solução de Problemas

• OPENROUTER_API_KEY não definido — exporte-o ou adicione ao .env.local na raiz do repositório.
• Modelo / qualidade — ajuste openrouter.translationModels e opções relacionadas em ai-i18n-tools.config.json.
• Glossário — edite documentation/glossary-user.csv ou regenere as strings da interface e execute novamente extract + translate.

Adicionando um novo idioma

1. Adicione a localidade ao i18n.locales e ao localeConfigs do Docusaurus em documentation/docusaurus.config.ts.
2. Adicione a mesma localidade ao targetLocales em ai-i18n-tools.config.json (raiz do repositório).
3. Execute pnpm i18n:generate-ui-languages na raiz, depois os comandos pnpm i18n:extract / translate conforme necessário.