Communitygithub.com

hd2-documentos-bilingües-verificar

Mantén honesto un par de documentos bilingües: verifica que un archivo markdown traducido aún coincida con su fuente recompilando sus bloques Lua en LuaJIT, comparando bloques de código tras eliminar comentarios, cotejando la estructura de encabezados y enlaces, y comparando árboles de directorios por estructura en lugar de prosa. Úsalo después de editar cualquiera de los lados de un par de documentos, o cuando las traducciones empiecen a desviarse del código.

¿Qué es hd2-documentos-bilingües-verificar?

Esta habilidad proporciona un script de verificación (`scripts/verify_translations.py`) diseñado para garantizar que los documentos bilingües (pares de archivos markdown, como `X.md` y `X_cn.md`) mantengan coherencia estructural y de código, permitiendo a los revisores centrarse en la calidad de la prosa traducida. Es especialmente útil en repositorios donde cada documento tiene una versión en inglés y otra en chino (u otros idiomas), y donde los bloques de código obsoletos en la copia traducida son errores difíciles de detectar. Soporta los principales agentes de IA para desarrollo (Claude Code, Cursor, Codex) y utiliza LuaJIT a través de la librería `lupa` para recompilar bloques Lua traducidos, además de realizar ocho comprobaciones adicionales sobre la estructura del documento. Funciona sin necesidad de juego, herramientas de carga o red; solo requiere Python 3.8+ y opcionalmente `lupa`. El script escribe únicamente en la salida estándar y no modifica archivos, lo que lo hace seguro para integrar en flujos de trabajo de CI/CD.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace hd2-documentos-bilingües-verificar?

English / 简体中文

Confianza: verificado aquí; ambos modos de fallo se provocaron deliberadamente.

scripts/verify_translations.py comprueba las cosas que una traducción no debe cambiar, para que la atención de la revisión pueda centrarse en la prosa en lugar de en si un ejemplo de código sigue siendo correcto.

Escrito después de que este repositorio creciera con un par inglés/chino para cada documento: seis pares de X.md / X_cn.md, donde un bloque de código obsoleto en la copia china es un error que nadie nota.

Requisitos previos

NecesidadPor quéSi falta
Python 3.8+el script—
luparecompila los bloques Lua traducidos en LuaJIT real (comprobación 1)las otras cinco comprobaciones siguen ejecutándose; el script imprime lo que omitió
los pares, en una estructura de repositorioel descubrimiento encuentra cualquier X.md con un X_cn.md a su lado, en cualquier parte del árbolapúntalo con --root

Nada más: sin juego, sin herramientas de carga, sin red. No escribe nada.

Uso

python -B scripts/verify_translations.py                     # escanea la raíz del repositorio
python -B scripts/verify_translations.py --root <repo>       # o apunta a uno
python -B scripts/verify_translations.py --no-luajit         # fuerza el modo degradado

Salida 0 = cada par pasó; distinto de cero = al menos uno falló, con el par nombrado.

Las nueve comprobaciones

  1. El Lua traducido aún compila en LuaJIT — extrae cada bloque lua de la traducción y lo compila. Detecta una traducción que tocó código.

  2. Los bloques de código coinciden con la fuente tras eliminar todos los comentarios — -- y --[[ ]] para Lua, # para shell/PowerShell y Python (un comentario en línea # … es texto traducible), ; para pseudocódigo. Los comentarios se traducen; el código no.

  3. Los bloques de documentación se comparan como documentación — un bloque cuenta como documentación cuando no tiene código ejecutable, es decir, un árbol de directorios / diseño de paquete, un bloque de text con prosa, o un bloque de código que contiene solo un docstring o comentarios. Los árboles se comparan por esqueleto (glifos, sangría, primer token por línea), lo que sigue detectando una rama omitida o una ruta renombrada; la prosa se compara solo por número de líneas, porque cada palabra está traducida.

  4. La estructura de encabezados coincide — cantidad y niveles, en orden. Detecta una sección omitida.

  5. Cada enlace relativo se mantiene, o se redirige deliberadamente a un par _cn (se informa como nota, no como fallo). Que la fuente apunte a un archivo _cn que la traducción es también es una nota.

  6. El frontmatter está intacto — mismas claves, name: sin cambios (es un identificador), y description: traducido (es lo que ve un lector al elegir la habilidad).

  7. El conmutador de idioma existe, una vez, y apunta a la contraparte — en el bloque de encabezado de ambos lados, con el idioma actual sin enlace:

    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) / 简体中文
    

    Las URLs absolutas son deliberadas — copiadas de los propios repositorios de DeepSeek, porque el conmutador es el único enlace que un lector necesita antes de poder navegar cualquier otra cosa. Se verifica en lugar de confiar: eliminar uno, apuntarlo al archivo equivocado o dejar dos en el encabezado hacen que la ejecución falle.

  8. Cada archivo de habilidad lleva su propio conmutador, incluso sin traducción aún — verificado para cada SKILL.md y SKILL_cn.md en skills/, independientemente del emparejamiento. El bucle de pares solo se ejecuta cuando ambos lados existen, por lo que una habilidad con un archivo en inglés y sin traducción lo evita por completo: así es exactamente como cinco habilidades en inglés terminaron sin conmutador mientras que sus archivos chinos sí lo tenían.

  9. Los destinos de URLs absolutas de GitHub deben resolverse — informado por check_absolute_targets(), porque los conmutadores usan URLs absolutas por convención y una contraparte faltante es de otro modo un enlace muerto en la página renderizada que nadie nota.

Dos lecciones incorporadas

  • Un verificador que asume el diseño obvio reporta fallos falsos. La primera versión eliminaba solo comentarios de línea completa, por lo que cada bloque de código que contenía un comentario -- al final parecía una discrepancia. Arreglar el verificador, no las traducciones, fue la decisión correcta — y solo fue obvio porque el número de fallos era increíblemente alto. Lo mismo sucedió luego dos veces más: un comentario en línea # en un bloque de Python (el eliminador solo conocía shell), y un bloque python que contenía solo un docstring (sin código ejecutable en absoluto, por lo que todo el bloque es prosa). Cada arreglo hizo que la comprobación 3 fuera más estricta y precisa: comparar código como código, y documentación como documentación, y decidir eso a partir del contenido en lugar de la etiqueta del bloque.
  • La comprobación 3 existe también debido a un falso positivo. Cuatro bloques de "código" en una nueva habilidad eran árboles de directorios; tratar sus anotaciones traducidas como un cambio de código habría forzado al traductor a dejar la prosa en inglés.

Cuando un verificador reporta fallos, mira los fallos antes de tocar la traducción. En los tres casos anteriores las traducciones eran correctas — incluyendo aquella donde el "código" era un docstring que explicaba el incidente de despliegue, traducido a propósito. Un linter que se equivoca cuesta más que ningún linter: enseña a la gente a ignorarlo.

Limitaciones

  • Demuestra correspondencia estructural, no que la traducción sea correcta. Una frase mal traducida pasa todas las comprobaciones. Lee la prosa.
  • La huella estructural de la comprobación 3 ignora el texto de anotación por diseño, por lo que una traducción que reemplazó la descripción de una ruta por algo incorrecto no se detecta.
  • Solo conoce las estructuras en discover_pairs(); un repositorio organizado de manera diferente necesita que esa función se extienda.

Ver también

writing-mod-tools (degradación honesta, códigos de salida, declarar lo que una herramienta no puede hacer).

Skills relacionados