Skip to content

Commit 35742cb

Browse files
oidacraoidacra
committed
feat: incremental translation detection and tooling
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.
1 parent aef8cfe commit 35742cb

36 files changed

Lines changed: 3591 additions & 200 deletions

File tree

‎.agents/skills/batch-translate/SKILL.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
name: batch-translate
3+
description: Traducir múltiples archivos de documentación Angular en lote
4+
---
5+
6+
# Batch Translation Agent
7+
8+
Traduce múltiples archivos de documentación Angular del inglés al español de forma secuencial. Para cada archivo aplica el mismo proceso que `/translate-angular-docs`.
9+
10+
## Cuándo usar este agent
11+
12+
- Tienes una lista de archivos relacionados (ej. todos los guides de forms)
13+
- Quieres procesar una carpeta completa o sección
14+
- Necesitas un reporte de qué se tradujo y qué quedó pendiente
15+
16+
## Uso
17+
18+
Pasa una lista de archivos o describe la sección a traducir:
19+
20+
```
21+
/batch-translate guide/forms/overview.md guide/forms/reactive-forms.md guide/forms/validation.md
22+
```
23+
24+
O con una descripción:
25+
```
26+
/batch-translate todos los archivos sin traducir en reference/configs/
27+
```
28+
29+
---
30+
31+
## Proceso para cada archivo
32+
33+
### 1. Verificar estado
34+
35+
Antes de traducir, comprueba si el archivo ya está traducido:
36+
- Si existe `archivo.en.md` → el `archivo.md` ya fue traducido (saltar o confirmar con el usuario)
37+
- Si no existe `archivo.en.md` → el `archivo.md` está en inglés, proceder
38+
39+
### 2. Crear backup
40+
41+
```bash
42+
cp adev-es/src/content/<ruta>/archivo.md adev-es/src/content/<ruta>/archivo.en.md
43+
```
44+
45+
### 3. Leer el archivo original
46+
47+
Lee el contenido completo antes de traducir.
48+
49+
### 4. Traducir
50+
51+
Aplica todas las reglas del skill `/translate-angular-docs`:
52+
- Respeta el glosario de términos
53+
- Mantén el código intacto (traduce solo los comentarios)
54+
- Preserva el formato markdown
55+
- Mantén alineación de líneas cuando sea posible
56+
- Traduce las etiquetas `<docs-*>` correctamente
57+
58+
### 5. Escribir la traducción
59+
60+
Sobreescribe `archivo.md` con la traducción.
61+
62+
### 6. Verificar anchors
63+
64+
Si se tradujeron encabezados con enlaces internos, actualiza los anchors.
65+
66+
### 7. Stage en git
67+
68+
```bash
69+
git add adev-es/src/content/<ruta>/archivo.md adev-es/src/content/<ruta>/archivo.en.md
70+
```
71+
72+
---
73+
74+
## Reglas del batch
75+
76+
- **Procesar secuencialmente**, un archivo a la vez (no en paralelo)
77+
- **Confirmar antes de empezar** si la lista tiene más de 5 archivos
78+
- **No mezclar archivos** de carpetas muy distintas en un mismo commit
79+
- **Pausar si hay duda** sobre algún término técnico no listado en el glosario — preguntar al usuario
80+
81+
---
82+
83+
## Reporte final
84+
85+
Al terminar, entrega un resumen con este formato:
86+
87+
```
88+
## Resumen de traducción
89+
90+
✅ Traducidos (N archivos):
91+
- guide/forms/overview.md
92+
- guide/forms/reactive-forms.md
93+
94+
⏭️ Omitidos (ya tenían .en.md):
95+
- guide/forms/validation.md
96+
97+
❌ Con problemas:
98+
- guide/forms/template-driven.md → razón
99+
100+
## Próximos pasos
101+
102+
git commit -m "translate: translations for forms guides"
103+
```
104+
105+
---
106+
107+
## Commit al finalizar el lote
108+
109+
Agrupa los archivos de la misma sección en un solo commit:
110+
111+
```bash
112+
# Formato:
113+
git commit -m "translate: translations for <sección>"
114+
115+
# Ejemplos:
116+
# translate: translations for forms guides
117+
# translate: translations for reference configs section
118+
# translate: complete translation of routing guides
119+
```
120+
121+
Si los archivos son de secciones distintas, haz commits separados por sección.

‎.agents/skills/crear-issues-traduccion/SKILL.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
name: crear-issues-traduccion
3+
description: Crear los issues de traducción del pendiente, con título, etiquetas y criterios de aceptación según la convención del repo
4+
---
5+
6+
# Crear issues de traducción
7+
8+
Convierte el pendiente detectado en issues de GitHub bien formados. El agrupado
9+
lo calcula la herramienta; lo que aporta este skill es lo que un script no
10+
acierta: **nombrar** cada lote y escribir sus criterios de aceptación.
11+
12+
## Paso 1 — Obtener el pendiente agrupado
13+
14+
```shell
15+
npm run check-translations -- --issues
16+
```
17+
18+
Devuelve lotes ya agrupados por carpeta, subiendo de nivel cuando una carpeta no
19+
reúne suficientes archivos. Cada lote sale marcado con `← renombra esto`: ese es
20+
tu trabajo.
21+
22+
Si necesitas los datos crudos —para contar, filtrar o ver los diffs—:
23+
24+
```shell
25+
npm run check-translations -- --json
26+
```
27+
28+
## Paso 2 — Comprobar qué ya existe
29+
30+
**Antes de crear nada.** El repo mantiene estos issues a mano y duplicarlos es
31+
peor que no crearlos:
32+
33+
```shell
34+
gh issue list --state open --limit 100 --search "traducir OR actualizar"
35+
```
36+
37+
Si un lote ya tiene issue, no lo abras de nuevo. Si el issue existe pero le
38+
faltan archivos que ahora sí detectamos, **coméntalo** en vez de abrir otro.
39+
40+
## Paso 3 — Componer el título
41+
42+
Cuatro patrones, todos sacados del historial del repo:
43+
44+
| Situación | Patrón | Ejemplos reales |
45+
| --- | --- | --- |
46+
| Una carpeta de guías | `Traducir - Guías de <X>` | Guías de Errores · Guías de SSR · Guías de Componentes |
47+
| Un solo documento | `Traducir - Guía de <X>` | Guía de Seguridad · Guía de Tailwind · Guía Zoneless |
48+
| Un tutorial | `Traducir - Tutorial <X>` | Tutorial Signals · Tutorial Learn Angular |
49+
| Página con nombre propio | `Traducir - <Nombre>` | Press Kit · Roadmap · Releases |
50+
51+
Para traducciones desactualizadas, cambia el verbo: `Actualizar - Pasos del
52+
tutorial Learn Angular`.
53+
54+
Si las páginas las trae una versión nueva de Angular, antepón la versión:
55+
`[Angular 22.1] Traducir guías de Signal Forms`.
56+
57+
### Cómo nombrar la sección
58+
59+
La misma regla del glosario: **el descriptor va en español, el nombre de
60+
producto o API se queda en inglés.**
61+
62+
- `reference/errors` → **Guías de Errores**
63+
- `guide/forms/signals` → **Guías de Signal Forms** (no «Formularios de Señales»)
64+
- `guide/di` → **Guías de Inyección de Dependencias**
65+
- `tools/devtools` → **Guías de Devtools**
66+
- `guide/zoneless` → **Guía Zoneless**
67+
68+
Ante la duda, **mira cómo se llama esa sección en el menú**: ahí ya está
69+
traducida y decidida por alguien.
70+
71+
```shell
72+
grep -n "label:" adev-es/src/app/routing/navigation-entries/index.ts | grep -i <sección>
73+
```
74+
75+
Ese archivo es la mejor referencia de estilo que hay. Por ejemplo:
76+
77+
| En el menú | Qué enseña |
78+
| --- | --- |
79+
| `Enciclopedia de Errores` | el descriptor se traduce |
80+
| `Inyección de Dependencias` | término establecido, en español |
81+
| `Estado dependiente con linkedSignal` | el nombre de la API se queda en inglés |
82+
83+
Nunca uses la ruta como título. `reference/errors` es el dato de entrada, no el
84+
nombre.
85+
86+
## Paso 4 — Elegir etiquetas
87+
88+
- `docs-translation` — **siempre**. El 17 % de los issues del repo no la tiene, y
89+
por eso las búsquedas por etiqueta no son fiables.
90+
- `good first issue` — solo si el lote es pequeño (1–3 archivos), sin bloques de
91+
código complejos y sin terminología nueva.
92+
- `help wanted` — cuando el lote es grande y conviene repartirlo.
93+
94+
No inventes etiquetas: usa las que existen (`gh label list`).
95+
96+
## Paso 5 — Escribir el cuerpo
97+
98+
Estructura fija:
99+
100+
```markdown
101+
<una frase de contexto: de dónde salen estas páginas>
102+
103+
## Archivos
104+
105+
- [ ] `archivo.md`
106+
- [ ] `otro.md`
107+
108+
## Criterios de aceptación
109+
110+
- [ ] Cada archivo tiene su `.en.md` con el original en inglés
111+
- [ ] `npm run lint-glossary` no reporta problemas en los archivos tocados
112+
- [ ] `npm run check-translations` ya no los lista
113+
- [ ] Los prefijos de alerta (`NOTE:`, `TIP:`, `IMPORTANT:`…) siguen en inglés
114+
- [ ] `.md` y `.en.md` van en el mismo commit
115+
```
116+
117+
Para un lote de **actualización** los criterios cambian, porque el trabajo es otro:
118+
119+
```markdown
120+
## Criterios de aceptación
121+
122+
- [ ] Solo se tocaron los bloques que cambiaron en el original
123+
- [ ] `npm run verify-translation -- <ruta>` pasa en cada archivo
124+
- [ ] `npm run check-translations` ya no los lista
125+
- [ ] `.md` y `.en.md` van en el mismo commit
126+
```
127+
128+
### Sobre los criterios
129+
130+
Son verificables con un comando, a propósito. Un criterio como «la traducción
131+
suena natural» no se puede marcar como cumplido sin discutir; «`lint-glossary`
132+
no reporta problemas» sí.
133+
134+
En los lotes de actualización, incluye el conteo de líneas por archivo que da la
135+
herramienta: distingue el trabajo de dos minutos del de media hora y ayuda a
136+
repartir.
137+
138+
## Paso 6 — Crear el issue
139+
140+
```shell
141+
gh issue create \
142+
--title "Traducir - Guías de Errores" \
143+
--label docs-translation \
144+
--body-file cuerpo.md
145+
```
146+
147+
Usa `--body-file`: pasar markdown largo con `--body` se rompe con las comillas y
148+
los saltos de línea.
149+
150+
> [!IMPORTANT]
151+
> Crear issues es una acción visible para toda la comunidad. **Enseña los
152+
> borradores y espera confirmación antes de ejecutar `gh issue create`**, incluso
153+
> si te pidieron crearlos. Un lote mal agrupado o mal nombrado hay que cerrarlo a
154+
> mano después.
155+
156+
## Qué no hacer
157+
158+
- **No abrir un issue por archivo.** El repo agrupa por sección; 31 issues para
159+
31 archivos es ruido que nadie atiende.
160+
- **No mezclar traducir con actualizar** en el mismo issue: el procedimiento es
161+
distinto y los criterios de aceptación también.
162+
- **No incluir archivos huérfanos.** Si `check-translations` los lista como
163+
huérfanos, esas páginas ya no existen en el original: hay que borrarlas, no
164+
traducirlas.
165+
- **No usar la ruta como título.**

0 commit comments

Comments
 (0)