Tradução automática
Esta página foi traduzida automaticamente por IA e pode conter erros. Se algo não estiver claro, consulte a fonte em inglês.
Internacionalização¶
A documentação trata o inglês e o chinês simplificado como fontes canônicas revisadas.
Cada outra localidade habilitada é um derivado gerado. O registro de idiomas, o roteamento de fontes, a configuração do modelo e os limites da API residem em
i18n/config.toml.
1. Cobertura de idiomas e roteamento de fontes¶
O registro intencionalmente habilita um conjunto focado de 12 localidades do site. Ele cobre todos os seis idiomas oficiais das Nações Unidas: árabe, chinês, inglês, francês, russo e espanhol. Adicionalmente, cobre japonês, coreano e chinês tradicional para a Ásia Oriental, além de alemão, italiano e português para a Europa. Inglês e chinês simplificado são canônicos, portanto 10 localidades são traduzidas por máquina.
Japonês, coreano e chinês tradicional usam o chinês simplificado como sua fonte. Todas as outras localidades geradas usam o inglês. A seleção da fonte é explícita por localidade; o tradutor nunca adivinha a partir de um nome de localidade ou de caracteres do documento.
Adicionar uma localidade requer entradas correspondentes em i18n/config.toml e na lista de idiomas do MkDocs
i18n. A auditoria de documentação rejeita registros inconsistentes.
2. Contrato de documento canônico¶
Cada página do MkDocs tem um arquivo em inglês e um arquivo .zh-CN.md. Um pull request,
push para main, ou execução de qualidade acionada manualmente que altere uma versão canônica
deve incluir sua contraparte no intervalo de commits verificado. O fluxo de trabalho de qualidade verifica:
- pares canônicos e acoplamento de pares alterados;
- paridade de nível de cabeçalho e bloco de código;
- links locais e referências de fonte;
- inventários de fixtures e testes;
- uma compilação estrita de cada localidade configurada.
O texto canônico pode ser escrito manualmente ou com assistência de IA, mas deve ser commitado e revisado como fonte comum. A API de tradução nunca é chamada a partir de um fluxo de trabalho de pull request.
3. Numeração de cabeçalhos e estabilidade de fragmentos¶
A fonte Markdown armazena texto descritivo de cabeçalho sem números de estrutura.
Durante cada compilação do MkDocs, scripts/mkdocs_heading_numbers.py adiciona números
locais à página para cabeçalhos H2–H6. As páginas do Guia do Usuário usam letras minúsculas em H2
(a., b.) e descendentes de letra mais decimal (a.1, a.1.1); outras páginas
mantêm estruturas de página decimais. Separadamente, a navegação esquerda do Guia do Usuário usa
números decimais hierárquicos, como 1.1. Os títulos de página H1 e as seções de navegação de nível superior
permanecem sem numeração. Números gerados são metadados de apresentação:
mover uma seção altera seu número visível sem alterar seu identificador de fragmento.
O hook de compilação torna cada identificador de cabeçalho explícito antes de adicionar o
número visível. i18n/legacy-heading-anchors.json retém aliases para fragmentos
que foram publicados antes da remoção dos números de estrutura armazenados. Não edite
esse mapa de compatibilidade gerado casualmente e não adicione números de estrutura
manuais de volta ao Markdown canônico ou gerado; a auditoria de documentação
os rejeita.
4. Contrato de documento gerado¶
As páginas geradas usam o modo de sufixo do MkDocs, como index.fr.md ou
guide/configuration.ja.md. Cada página contém metadados determinísticos
registrando:
- a localidade e o caminho da fonte canônica;
- o resumo SHA-256 da fonte;
- o modelo resolvido e a versão do prompt;
- que a página é uma tradução automática.
i18n/manifest.json adicionalmente registra resumos de saída e impressões digitais de entrada de tradução.
Uma página fica desatualizada quando sua fonte, glossário, prompt, modelo ou
saída gerada mudam. O tradutor só solicita unidades desatualizadas, a menos que
uma reconstrução completa seja explicitamente solicitada.
Os cabeçalhos traduzidos mantêm seus slugs localizados naturais e recebem aliases ocultos para os slugs canônicos da fonte. Como os destinos de links Markdown são protegidos de alterações de modelo, esses aliases mantêm links de fragmento na mesma página e entre páginas válidos em cada localidade. Os aliases podem ser atualizados offline sem outra chamada de API de tradução.
Arquivos gerados não devem ser editados manualmente. O fluxo de trabalho de tradução do branch principal
os regenera e faz checkpoint de cada localidade concluída como um commit
em um branch apenas de gerados derivado do SHA exato validado por qualidade. Uma
execução posterior pode verificar e reutilizar esse branch, portanto uma interrupção apenas descarta
a localidade ainda em andamento. main permanece inalterado até que o fluxo de trabalho tenha
executado a auditoria de idioma gerado necessária, o conjunto de testes completo e a compilação
estrita de todas as localidades. Em seguida, verifica se main não avançou, promove o
checkpoint validado por um push fast-forward e implanta esse mesmo artefato de site validado.
5. Markdown protegido e contrato de prompt¶
Antes de uma solicitação de API, o tradutor substitui metadados, código em bloco, código inline, destinos de links, tags HTML e URLs simples por placeholders imutáveis. Uma resposta é rejeitada se algum placeholder estiver faltando, duplicado, inventado ou movido para fora do contrato de saída recuperável.
O prompt também exige níveis de cabeçalho e idiomas de bloco de código idênticos. A implementação verifica independentemente essas propriedades após restaurar o conteúdo protegido. A saída da tradução deve ser um objeto JSON; texto ao redor do JSON, conteúdo vazio, motivos de conclusão anormais ou esquemas incompatíveis são falhas.
Os prompts de Markdown e catálogo de navegação são versionados em
i18n/prompts/. i18n/glossary.json carrega terminologia estável de produto e comando.
6. Configuração do modelo e credenciais¶
O modelo padrão é configurado como deepseek-v4-flash. A implementação não
ramifica nesse nome. Uma futura alteração de modelo requer apenas a atualização de
i18n/config.toml, passando --model ou definindo a
variável de fluxo de trabalho DEEPSEEK_TRANSLATION_MODEL. O modelo resolvido é registrado
em cada página gerada e entrada de manifesto.
O GitHub Actions lê a credencial da API apenas do segredo do repositório chamado
DEEKSEEK_API_KEY. Ela é injetada apenas na etapa de geração quando o
plano offline relata unidades pendentes baseadas em API. Nunca está disponível para
código de pull request não confiável ou etapas de planejamento, limpeza e validação sem API.
Os valores de autenticação nunca são escritos em logs, arquivos gerados, artefatos
ou no manifesto.
7. Aviso na página e preferência de idioma¶
As páginas geradas por máquina recebem um aviso localizado no momento da renderização. O aviso identifica a página como uma tradução por IA, fornece um link para a fonte autoritativa em inglês ou chinês simplificado e um link para um issue de tradução pré-preenchido. Não faz parte do Markdown traduzido e não cria uma entrada no sumário.
Na primeira visita à página raiz de um visitante, o site compara navigator.languages
com as alternativas de idioma configuradas. Uma localidade compatível é selecionada
quando disponível. Uma seleção manual de idioma é salva localmente e tem
precedência em visitas posteriores.
8. Comandos do mantenedor¶
Mostrar o número de unidades de tradução pendentes sem fazer chamadas de rede:
uv run python scripts/translate_docs.py --plan
Verificar se cada página gerada e catálogo estão atualizados:
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
Atualizar aliases de cabeçalho de fonte estáveis sem chamadas de API:
uv run python scripts/translate_docs.py --refresh-heading-anchors
Forçar uma regeneração completa com um modelo explícito:
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash