hd2-bilingual-doc-verify
English / 简体中文
Confiança: verificado aqui; ambos os seus modos de falha foram provocados deliberadamente.
scripts/verify_translations.py verifica as coisas que uma tradução não deve alterar, para que a atenção da revisão possa ir para a prosa em vez de verificar se um exemplo de código ainda está correto.
Escrito depois que este repositório ganhou um par inglês/chinês para cada documento: seis pares de
X.md / X_cn.md, onde um bloco de código desatualizado na cópia chinesa é um bug que ninguém nota.
Pré-requisitos
| Necessidade | Por quê | Se estiver faltando |
|---|---|---|
| Python 3.8+ | o script | — |
lupa | recompila os blocos Lua traduzidos no LuaJIT real (verificação 1) | as outras cinco verificações ainda são executadas; o script imprime o que foi pulado |
| os pares, em uma estrutura de repositório | a descoberta encontra qualquer X.md com um X_cn.md ao lado, em qualquer lugar da árvore | aponte com --root |
Nada mais: sem jogo, sem ferramentas de carregamento, sem rede. Não escreve nada.
Uso
python -B scripts/verify_translations.py # verifica a raiz do repositório
python -B scripts/verify_translations.py --root <repo> # ou aponte para um
python -B scripts/verify_translations.py --no-luajit # força o modo degradado
Saída 0 = todos os pares passaram; diferente de zero = pelo menos um falhou, com o par nomeado.
As nove verificações
- Lua traduzido ainda compila no LuaJIT — extrai cada cerca
luada tradução e a compila. Pega uma tradução que tocou no código. - Cercas de código correspondem ao original após remover todos os comentários —
--e--[[ ]]para Lua,#para shell/PowerShell e Python (um comentário# ...inline é texto traduzível),;para pseudocódigo. Comentários são traduzidos; código não. - Cercas de documentação são comparadas como documentação — uma cerca conta como documentação quando não tem código executável, ou seja, uma árvore de diretórios / estrutura de pacotes, um bloco
textde prosa, ou uma cerca de código que cita apenas um docstring ou comentários. Árvores são comparadas pelo esqueleto (glifos, indentação, primeiro token por linha), o que ainda pega um ramo removido ou um caminho renomeado; a prosa é comparada apenas pela contagem de linhas, porque cada palavra é traduzida. - Estrutura de cabeçalhos corresponde — contagem e níveis, em ordem. Pega uma seção removida.
- Cada link relativo é mantido, ou é deliberadamente redirecionado para um par
_cn( relatado como nota, não como falha). O original apontando para um arquivo_cnque a tradução é também é uma nota. - Frontmatter está intacto — mesmas chaves,
name:inalterado (é um identificador), edescription:traduzido (é o que um leitor vê ao escolher a skill). - O alternador de idiomas existe, uma vez, e aponta para a contraparte — no bloco de cabeçalho de ambos os lados, com o idioma atual sem link:
URLs absolutas são intencionais — copiadas dos próprios repositórios do DeepSeek, porque o alternador é o único link que um leitor precisa antes de poder navegar em qualquer outra coisa. É verificado, não confiado: remover um, apontá-lo para o arquivo errado ou deixar dois no cabeçalho fazem a execução falhar.English / [简体中文](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README_cn.md) [English](https://github.com/Puipipi/HD2-Agent-Skills/blob/main/README.md) / 简体中文 - Cada arquivo de skill carrega seu próprio alternador, mesmo sem tradução ainda — verificado para cada
SKILL.mdeSKILL_cn.mdemskills/, independentemente do pareamento. O loop de pares só é executado quando ambos os lados existem, então uma skill com um arquivo inglês e sem tradução escapa completamente: é exatamente assim que cinco skills em inglês ficaram sem alternador enquanto seus arquivos chineses tinham um. - Alvos de URL absoluta do GitHub devem resolver — relatados por
check_absolute_targets(), porque os alternadores usam URLs absolutas por convenção e uma contraparte ausente é, de outra forma, um link morto na página renderizada que ninguém nota.
Duas lições incorporadas
- Um verificador que assume o layout óbvio relata falsas falhas. A primeira versão removia apenas comentários de linha inteira, então todo bloco de código contendo um comentário
--final parecia uma incompatibilidade. Corrigir o verificador, não as traduções, foi a decisão certa — e só ficou óbvio porque a contagem de falhas era implausivelmente alta. A mesma coisa aconteceu mais duas vezes: um comentário#inline em uma cerca Python (o removedor só conhecia shell), e uma cercapythonque citava apenas um docstring (nenhum código executável, então todo o bloco é prosa). Cada correção tornou a verificação 3 mais restrita e mais verdadeira: compare código como código, e documentação como documentação, e decida isso a partir do conteúdo, não do rótulo da cerca. - A verificação 3 existe por causa de um falso positivo também. Quatro cercas de "código" em uma nova skill eram árvores de diretórios; tratar suas anotações traduzidas como uma alteração de código teria forçado o tradutor a deixar a prosa em inglês.
Quando um verificador relata falhas, olhe para as falhas antes de tocar na tradução. Em todos os três casos acima, as traduções estavam corretas — incluindo aquela onde o "código" era um docstring explicando o incidente de implantação, traduzido de propósito. Um linter que está errado custa mais do que nenhum linter: ensina as pessoas a ignorá-lo.
Limitações
- Ele prova correspondência estrutural, não que a tradução está correta. Uma frase mal traduzida passa em todas as verificações. Leia a prosa.
- A impressão digital estrutural da verificação 3 ignora o texto de anotação por design, então uma tradução que substituiu a descrição de um caminho por algo errado não é pega.
- Ele só conhece os layouts em
discover_pairs(); um repositório organizado de forma diferente precisa dessa função estendida.
Veja também
writing-mod-tools (degradação honesta, códigos de saída, declarando o que uma ferramenta não pode fazer).