feat: herramientas de detección y traducción incremental - #206
Open
oidacra wants to merge 3 commits into
Open
Conversation
oidacra
force-pushed
the
poc/incremental-translation
branch
5 times, most recently
from
September 2, 2026 23:43
fc96c16 to
48b3eef
Compare
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
force-pushed
the
poc/incremental-translation
branch
from
September 2, 2026 23:43
48b3eef to
fa9c98d
Compare
… 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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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-translationsreconstruye el estado desde el historial de git,sin metadata adicional. Como
update-originsobrescribe el.en.mdcon elinglé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.
.mdCubre también
.tsy.html, que se traducen igual —el menú, el pie, laportada— y no se vigilaban.
Traducción incremental
Para una traducción desactualizada,
plan-translationcalcula qué bloques hayque tocar y
verify-translationcomprueba 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.mdsalía como 1 bloque de 37, ydrag-drop.mdcomo reestructuración, que el sistema rechaza en vez de fingirprecisión.
Cambios en el flujo existente
update-originfalla si un objetivo de copia no coincide con nada, en vezde 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 eldetector para que ambos no puedan discrepar.
sus copias: el build superpone
adev-essobreorigin, así que dejarlas lascongelaba en una versión vieja.
CONTRIBUTINGdocumenta el flujo y corrige el consejo de que las traduccionesparciales no necesitan
.en.md. Es exactamente lo que dejótranslation-files.mdsin 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.mtsconstruye su matcher desde un enum con las clavesen inglés, así que
NOTA:no coincide y el aviso se renderiza como párrafoplano. 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-glossaryaplicaglosario.ymlignorando código, enlaces, anchors yatributos 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 —
paquetesonpaquetes npm en 218 casos,
fragmentoson fragmentos de código en 88—. Unlinter 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ñadetranslate-deltapara el flujoincremental y
crear-issues-traduccion, cuya convención de títulos sale delhistorial del repo.
Verificación
63 tests (
npm test), sobre lo que puede romperse en silencio: el parser debloques, 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.