Skip to content

feat: herramientas de detección y traducción incremental - #206

Open
oidacra wants to merge 3 commits into
mainfrom
poc/incremental-translation
Open

feat: herramientas de detección y traducción incremental#206
oidacra wants to merge 3 commits into
mainfrom
poc/incremental-translation

Conversation

@oidacra

@oidacra oidacra commented Aug 19, 2026

Copy link
Copy Markdown
Member

Herramientas para saber qué falta traducir, qué se desactualizó, y aplicar los
cambios del original sin retraducir el archivo entero.

Nace de una pregunta concreta: cuando Angular cambia una página ya traducida,
¿cómo se detecta y cómo se actualiza sin rehacer el trabajo?

Qué se detecta y cómo

npm run check-translations reconstruye el estado desde el historial de git,
sin metadata adicional. Como update-origin sobrescribe el .en.md con el
inglés nuevo, ese archivo en el commit donde se tradujo es el inglés vigente
entonces; compararlo con el actual da exactamente lo que falta.

Distingue cinco estados. Los tres últimos eran silenciosos: esos archivos se
contaban como correctos.

Estado Hoy Qué pasaba antes
Sincronizadas 318
Desactualizadas 31
Sin traducir 37
Sin respaldo 0 se destruían en el siguiente sync, sin aviso
Desparejadas 0 invisibles: el bucle solo recorría los .md
Huérfanas 0 se contaban como sincronizadas para siempre

Cubre también .ts y .html, que se traducen igual —el menú, el pie, la
portada— y no se vigilaban.

Traducción incremental

Para una traducción desactualizada, plan-translation calcula qué bloques hay
que tocar y verify-translation comprueba que no se tocó nada más.

El principio es leer mucho y escribir poco: el modelo lee el documento
completo en ambos idiomas —la traducción existente es la mejor referencia de
terminología y registro que hay— pero solo edita los bloques declarados.

La verificación de aislamiento convierte «no rompas el resto del archivo» de
promesa del prompt en invariante comprobable. Sobre los dos archivos
desactualizados de entonces: selectors.md salía como 1 bloque de 37, y
drag-drop.md como reestructuración, que el sistema rechaza en vez de fingir
precisión.

Cambios en el flujo existente

  • update-origin falla si un objetivo de copia no coincide con nada, en vez
    de omitirlo en silencio. Es la causa raíz del desfase que feat: update origin to Angular v22.1 #192 corrigió a
    mano. La lista de objetivos pasa a tools/lib/targets.mjs, compartida con el
    detector para que ambos no puedan discrepar.
  • Se excluyen readmes de apps de ejemplo y páginas índice sin prosa, y se borran
    sus copias: el build superpone adev-es sobre origin, así que dejarlas las
    congelaba en una versión vieja.
  • CONTRIBUTING documenta el flujo y corrige el consejo de que las traducciones
    parciales no necesitan .en.md. Es exactamente lo que dejó
    translation-files.md sin protección durante meses.

Corrección de contenido

El skill de traducción mandaba traducir los prefijos de alerta. Son claves del
tokenizer
: docs-alert.mts construye su matcher desde un enum con las claves
en inglés, así que NOTA: no coincide y el aviso se renderiza como párrafo
plano. Hay 425 así, recogidos en #204.

El skill ya no lo hace, y el linter los detecta. Este PR no toca el corpus.

Terminología

lint-glossary aplica glosario.yml ignorando código, enlaces, anchors y
atributos de ruta. Cada regla lleva su motivo.

Se mantiene deliberadamente pequeño: se midieron los candidatos del glosario del
skill contra el corpus y la mayoría daría falsos positivos —paquete son
paquetes npm en 218 casos, fragmento son fragmentos de código en 88—. Un
linter que falla siempre acaba ignorado.

Skills

Los cuatro estaban en formato plano y ninguno se cargaba: Claude Code espera
<nombre>/SKILL.md. Se corrige, y se añade translate-delta para el flujo
incremental y crear-issues-traduccion, cuya convención de títulos sale del
historial del repo.

Verificación

63 tests (npm test), sobre lo que puede romperse en silencio: el parser de
bloques, el agrupado, las reglas del glosario, y que los objetivos de copia
coincidan de verdad con el original.

El detector se validó contra #192 antes de mergearse: marcó 31 desactualizadas y
14 huérfanas, y las 14 coincidían una a una con las que su autor había
encontrado a mano.

No incluye

Ninguna automatización de CI ni creación automática de issues: se decidió que
los issues se crean a mano, agrupados por sección, porque nombrarlos es una
decisión editorial. Tampoco toca el contenido traducido.

@oidacra
oidacra requested review from Splaktar and ricardochl August 19, 2026 23:32
@oidacra
oidacra force-pushed the poc/incremental-translation branch 5 times, most recently from fc96c16 to 48b3eef Compare September 2, 2026 23:43
Reliable detection of pending translation work, plus the tooling to handle
it block by block instead of retranslating whole files.

- Detection: check-translations compares against the English original
  instead of guessing the language, watches the site UI as well as the
  markdown, flags orphaned pages, and groups pending work into
  issue-sized batches.
- Incremental translation: plan-translation reports which blocks to touch
  and verify-translation checks that nothing else changed.
- Glossary: the linter no longer counts HTML attributes and link
  definitions, while still checking the ones that carry translatable prose.
- Backups: update-origin protects links.ts and stops translating alert
  prefixes, which broke 425 callouts.
- Conventions: AGENTS.md as the shared agent instructions, skills under
  .agents with a symlink for Claude Code, plus issue and pull request
  templates.
@oidacra
oidacra force-pushed the poc/incremental-translation branch from 48b3eef to fa9c98d Compare September 2, 2026 23:43
… the wrong anchor rule

Lessons from the first nine translation PRs, where five of them broke the
docs build.

- lint-glossary took `argv._[0]`, so `lint-glossary -- a.md b.md` silently
  checked only `a.md` and reported success. It now takes every path, and
  fails on one that matches no translation instead of passing green on a
  typo. Covered by tests.
- The quality checklist said "internal links point to the translated
  anchors", which is exactly what broke the build: translating a heading
  changes its anchor and orphans every link pointing at it, from this page
  and from others. Headings now keep the English anchor via `{#anchor}`.
  batch-translate carried the same wrong instruction.
- The skills said nothing about delivery. They now state one commit per
  issue, an English message with `Fixes #<issue>`, `.md` and `.en.md`
  together, and no tool attribution in the commit or the PR body.

CONTRIBUTING carries the same two rules for human contributors.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant