Communitygithub.com

Puipipi/Verificação de Documentos Bilíngues HD2

Mantenha um par de documentos bilíngues honesto — verifique se um arquivo markdown traduzido ainda corresponde ao original recompilando seus blocos Lua no LuaJIT, comparando cercas de código após remoção de comentários, combinando estrutura de cabeçalhos e links, e comparando árvores de diretórios por estrutura em vez de prosa. Use após editar qualquer lado de um par de documentos, ou quando as traduções começarem a se desviar do código.

O que é Verificação de Documentos Bilíngues HD2?

Esta skill, Puipipi/Verificação de Documentos Bilíngues HD2 (hd2-bilingual-doc-verify), fornece um script Python (`scripts/verify_translations.py`) que valida a integridade estrutural de pares de documentos markdown bilíngues (ex: `X.md` e `X_cn.md`). Ela é projetada para desenvolvedores e tradutores que mantêm traduções lado a lado, garantindo que a versão traduzida não tenha alterado inadvertidamente código, estrutura de cabeçalhos, links ou outros elementos não-traduzíveis. A ferramenta executa nove verificações abrangentes, que vão desde a recompilação de blocos Lua no LuaJIT (usando a biblioteca `lupa`) até a comparação de cercas de código após remoção de comentários, verificação da estrutura de cabeçalhos, preservação de links relativos e integridade do frontmatter. Ela suporta ambientes Python 3.8+ e é independente de plataforma, podendo ser usada em qualquer repositório com pares de documentos. A habilidade foi desenvolvida para o repositório HD2-Agent-Skills no GitHub e é particularmente útil para projetos que utilizam documentação bilíngue, como guias de modificação (modding) ou ferramentas de desenvolvimento, onde a precisão técnica é crítica. A saída do script é um código de saída (0 para sucesso, não-zero para falhas), facilitando a integração em pipelines de CI/CD. A ferramenta foi refinada com base em falsos positivos reais, aprendendo a diferenciar código de documentação (como árvores de diretórios ou docstrings) para evitar alarmes falsos.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Puipipi/HD2-Agent-Skills/tree/HEAD/skills/hd2-bilingual-doc-verify

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

NecessidadePor quêSe estiver faltando
Python 3.8+o script—
luparecompila 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órioa descoberta encontra qualquer X.md com um X_cn.md ao lado, em qualquer lugar da árvoreaponte 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

  1. Lua traduzido ainda compila no LuaJIT — extrai cada cerca lua da tradução e a compila. Pega uma tradução que tocou no código.
  2. 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.
  3. 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 text de 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.
  4. Estrutura de cabeçalhos corresponde — contagem e níveis, em ordem. Pega uma seção removida.
  5. Cada link relativo é mantido, ou é deliberadamente redirecionado para um par _cn ( relatado como nota, não como falha). O original apontando para um arquivo _cn que a tradução é também é uma nota.
  6. Frontmatter está intacto — mesmas chaves, name: inalterado (é um identificador), e description: traduzido (é o que um leitor vê ao escolher a skill).
  7. 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:
    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) / 简体中文
    
    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.
  8. Cada arquivo de skill carrega seu próprio alternador, mesmo sem tradução ainda — verificado para cada SKILL.md e SKILL_cn.md em skills/, 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.
  9. 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 cerca python que 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).

Habilidades Relacionadas