Saltar al contenido principal

Documentación bilingüe de proyectos — inglés canónico + español

Toda la documentación de un repositorio Wiedii se mantiene en inglés y español, en archivos independientes (no un solo archivo con ambos idiomas), con navegación enriquecida que enlaza recíprocamente las versiones.

Principio: un idioma canónico, el otro lo sigue​

  • Inglés = canónico (fuente de verdad). Coherente con la política de que el código y las docs técnicas de repo se escriben en inglés (ver politicas-core). Es donde se edita primero.
  • Español = traducción que sigue al canónico. Nunca son dos fuentes iguales — el ES refleja el EN, no al revés. Esto evita el problema central de dos archivos: el drift (que una versión quede vieja y mienta).

Alcance​

Todas las docs del repo se mantienen bilingües: README, CONTRIBUTING, getting-started, ADRs, runbooks y todo docs/. (Los nombres literales —comandos, identificadores de código, flags— no se traducen.)

Cobertura total = máximo riesgo de desincronía → el mecanismo anti-drift de abajo es obligatorio, no opcional.

Convención de archivos y navegación​

  • Naming: X.md (inglés, canónico) + X.es.md (español). Para sitios de docs, docs/en/ + docs/es/. Consistencia dentro de cada repo.
  • Switcher en el encabezado de cada archivo, con enlace recíproco al par y al índice: 
    > 🇬🇧 **English** · [🇪🇸 Español](./README.es.md)
    > [🇬🇧 English](./README.md) · 🇪🇸 **Español**
  • Sitios de docs (Docusaurus / MkDocs / mdBook): usar el i18n nativo de la herramienta en vez de cross-links a mano — genera y mantiene la navegación entre idiomas automáticamente. Los cross-links manuales son solo para markdown plano en el repo.

Anti-drift (obligatorio)​

  1. Puntero de sincronización en cada archivo traducido: idioma canónico + commit con el que se sincronizó (p. ej. <!-- synced-with: README.md @ <sha> -->).
  2. Check de staleness que avise/falle si el canónico cambió y su traducción no se actualizó (compara el synced-with @ <sha> contra el último commit del canónico). En repos con CI es una etapa del pipeline; en repos sin CI (p. ej. el propio marketplace de plugins) se materializa equivalente vía pre-commit (lefthook) y/o los fact-collectors deterministas de /audit-project y /review-pr (audit-static-checks / review-static-checks) — el mismo patrón con que Wiedii sustituye CI en repos sin pipeline. El check emite un hecho (canónico movido, traducción detrás); la severidad la adjudica quien revisa.
  3. Skill del plugin de Claude (wiedii-dev, p. ej. bilingual-docs) que genere/actualice la traducción a partir del canónico y mantenga el switcher + el puntero synced-with — mismo patrón que las demás skills que materializan convenciones. Ver briefing del plugin.

Reconciliación con lo existente​

  • Reemplaza el patrón "un solo archivo con ambos idiomas" (scroll a la versión de abajo) por archivos independientes enlazados. (Aplica, p. ej., al README de este propio vault y al del marketplace claude-wiedii-plugins.)
  • La migración invierte el idioma primario donde el archivo único era ES-primario: el contenido canónico pasa a EN (X.md) y el ES a su traducción (X.es.md) con su puntero synced-with. Es un cambio deliberado, no automático — se hace doc por doc.
  • Extiende el precedente de contributing (CONTRIBUTING.md + CONTRIBUTING.es.md) a todas las docs del repo.

Referencias​