readme-i18n

Visión general de la skill readme-i18n

Qué hace readme-i18n

readme-i18n es una skill especializada para convertir un único README.md de estilo GitHub en un conjunto multilingüe de README que se pueda mantener con facilidad. No es una solución de localización general para aplicaciones. Su función principal es traducir el README de origen, crear archivos hermanos como README.zh.md, conservar la estructura de Markdown y la mecánica del repositorio, y añadir o normalizar un selector de idioma compartido en todas las variantes.

Quién debería usar readme-i18n

Esta skill encaja bien para maintainers, colaboradores de open source y agentes de IA que trabajan en la documentación de un repositorio cuando el objetivo real no es solo “traducir texto”, sino “publicar archivos README traducidos que sigan funcionando en GitHub”. Si te importa que badges, enlaces, bloques de código, nombres de archivo y selectores de idioma se mantengan consistentes, readme-i18n es un mejor punto de partida que un prompt genérico de traducción.

El trabajo real que resuelve

La mayoría de los intentos de traducir un README fallan por la estructura, no por el vocabulario. Lo que se necesita es un flujo de trabajo que:

• trate un archivo como fuente única de verdad
• mantenga el orden de las secciones alineado
• conserve comandos, rutas, código y la mecánica de los enlaces
• actualice todas las variantes de idioma de forma coherente
• evite selectores de idioma duplicados o rotos

Ese es el valor práctico de la readme-i18n skill.

Por qué esta skill es distinta de un prompt normal

La principal diferencia está en la lógica de decisión. La skill le indica al agente qué debe conservar exactamente, cuándo conviene pedir una aclaración una sola vez, cómo inferir convenciones a partir de archivos existentes y cómo actualizar un selector en su sitio en vez de crear otro. Las referencias incluidas son especialmente útiles para adoptarla porque reducen las suposiciones habituales sobre dónde colocar el selector y cómo manipular Markdown sin romper nada durante la traducción.

Cómo usar la skill readme-i18n

Contexto de instalación de readme-i18n

Instala la skill desde el repositorio xixu-me/skills en cualquier entorno compatible con Skills que ya estés usando. Si tu configuración admite instalaciones directas desde GitHub, el patrón habitual es:

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

Si tu entorno gestiona las skills de otra manera, usa la URL del repositorio https://github.com/xixu-me/skills/tree/main/skills/readme-i18n como referencia de origen y carga la skill desde skills/readme-i18n.

Archivos que conviene leer antes del primer uso

Para esta skill, la ruta de lectura más rápida y con mejor señal es:

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

Ese orden importa. SKILL.md explica el flujo de trabajo, la referencia del selector muestra la forma y ubicación esperadas del bloque, y la checklist de preservación deja claro qué debe permanecer sin cambios.

Qué entrada necesita readme-i18n

La skill funciona mejor cuando proporcionas:

• la ruta del README de origen, normalmente README.md
• el idioma de origen
• el idioma o los idiomas de destino
• cualquier glosario o término que no deba traducirse
• la convención de nombres existente, si el repositorio ya localiza sus README

Si no indicas los idiomas de destino, la skill está pensada para inspeccionar primero archivos traducidos existentes, selectores, nombres de archivo, issues o convenciones del repositorio. Si aun así el idioma no está claro, debería preguntar una vez en lugar de inventar destinos.

Suposiciones predeterminadas que conviene conocer

Los valores por defecto documentados son prácticos y merece la pena conocerlos antes de ejecutar readme-i18n:

• README.md en la raíz es la fuente única de verdad, salvo que indiques otra cosa
• se asume que el idioma de origen es inglés si no hay ambigüedad
• el orden de las secciones debe mantenerse alineado con el original
• si ya existe un esquema de nombres multilingüe, debe conservarse en vez de imponer uno nuevo

Estos valores por defecto hacen que la skill sea más segura para repositorios existentes que una solicitud de traducción en blanco.

Cómo escribir un buen prompt para readme-i18n

Una petición débil sería: “Traduce mi README al chino”.

Un prompt de readme-i18n usage más sólido sería:

• traducir README.md del inglés al chino simplificado
• crear README.zh.md
• conservar comandos, rutas, URLs de badges, bloques de código y enlaces relativos
• añadir un selector de idioma en la parte superior de ambos archivos
• mantener exactamente el mismo orden de encabezados
• no traducir el nombre del producto AcmeCLI ni las variables de entorno
• seguir cualquier convención de nombres existente si se detecta

Ese nivel extra de precisión mejora directamente la calidad de la salida porque encaja con las reglas de preservación y selector de la skill.

Flujo de trabajo de ejemplo para Translation

Un flujo práctico de readme-i18n for Translation sería:

1. Identificar cuál es el README fuente.
2. Comprobar si ya existen variantes traducidas.
3. Detectar el patrón de nombres de archivo del repositorio y el estilo actual del selector.
4. Traducir solo el contenido en lenguaje natural.
5. Conservar exactamente código, comandos, URLs y rutas de archivo.
6. Añadir o normalizar un único bloque de selector cerca de la parte superior de cada variante.
7. Verificar enlaces, formato y consistencia entre todos los archivos.

Ese es el modelo mental correcto: no “traducir texto”, sino “mantener una familia de README”.

Cómo debería funcionar el selector de idioma

El archivo de apoyo más importante de esta skill es la referencia del selector. Recomienda un único bloque de selector cerca de la parte superior de cada variante de README, normalmente después del título y del conjunto de badges, con marcadores estables:

<!-- README-I18N:START -->
<!-- README-I18N:END -->

Esos marcadores importan porque permiten que futuras ejecuciones actualicen el selector en su sitio. El idioma actual debe ir destacado y sin enlace; los demás idiomas sí deben ir enlazados. Mantén el mismo orden de idiomas en todas las variantes.

Qué debe preservarse exactamente

La checklist de preservación es la parte crítica para adoptar esta readme-i18n guide. En la práctica, no debes traducir:

• código inline
• bloques de código delimitados
• comandos, flags, variables de entorno y rutas
• URLs de badges y sus query params
• rutas de origen de imágenes
• la estructura de las tablas
• la mecánica de HTML en crudo

Traduce el texto visible, pero preserva la mecánica que hace que el README funcione.

Convenciones de repositorio que readme-i18n respeta

Si el repositorio ya usa un esquema de nombres distinto del predeterminado:

• README.md
• README.zh.md
• README.es.md

la skill debería conservar ese esquema. Esto es importante en repositorios que ya tienen una localización parcial, referencias en CI o expectativas de los colaboradores ligadas a los nombres de archivo.

Dónde readme-i18n ahorra más tiempo

Esta skill aporta más valor cuando existe alguno de estos bloqueos de adopción:

• necesitas mantener sincronizados varios archivos README localizados
• el repositorio ya tiene un selector de idioma desordenado o duplicado
• traducciones anteriores rompieron Markdown o enlaces
• quieres que las actualizaciones sean repetibles y no ediciones manuales aisladas

Si solo necesitas una traducción aproximada y privada para entender un README, probablemente esta skill implique más proceso del que necesitas.

Preguntas frecuentes sobre la skill readme-i18n

¿readme-i18n es buena opción para principiantes?

Sí, si tu objetivo es específicamente la localización de README. La skill acota la tarea con entradas claras y reglas de preservación, lo que resulta más sencillo que inventarte tu propio flujo de traducción. Aun así, las personas principiantes deben revisar la salida, especialmente los destinos de los enlaces, los encabezados y la consistencia del selector.

¿Cuándo debería usar readme-i18n en vez de un prompt de traducción normal?

Usa readme-i18n cuando el README traducido vaya a commitearse en un repositorio. Un prompt normal puede traducir demasiado, alterar ejemplos de código, romper enlaces de badges u olvidarse de la navegación entre archivos. Esta skill funciona mejor cuando la corrección del resultado importa más que la velocidad.

¿readme-i18n sirve solo para repositorios de GitHub?

Está optimizada para README de repositorio con estilo GitHub y sus convenciones de Markdown. También puede ayudar en otras plataformas Git, pero sus supuestos encajan mucho mejor con repositorios open source basados en README.md que con sitios completos de documentación o sistemas de localización de producto.

¿readme-i18n gestiona conjuntos completos de documentación?

No. Este flujo está centrado en README. Si necesitas i18n para una web, una app o una documentación completa, la readme-i18n skill se queda corta. Su fortaleza está en mantener coherentes un documento principal de entrada al repositorio y sus archivos hermanos localizados.

¿Qué idiomas puedo usar?

La skill es agnóstica al idioma siempre que especifiques los destinos o el repositorio ya los deje claros. Evita explícitamente inventar idiomas de destino cuando el repositorio no ofrece evidencia suficiente.

¿readme-i18n puede actualizar una configuración multilingüe de README que ya existe?

Sí, y de hecho es uno de sus mejores casos de uso. Está diseñada para inspeccionar archivos traducidos y selectores actuales, conservar convenciones de nombres y normalizar un conmutador existente en lugar de añadir un segundo.

¿Cuándo readme-i18n no encaja bien?

Es mejor omitirla cuando:

• solo quieres una traducción informal para lectura
• tu documentación vive fuera del README
• necesitas gestión terminológica en un corpus documental grande
• tu repositorio no quiere enlaces de selector de idioma dentro de los archivos README

En esos casos, puede encajar mejor un prompt más ligero o un flujo de localización documental más amplio.

Cómo mejorar la skill readme-i18n

Dale a readme-i18n restricciones de origen más fuertes

Cuanto mejores sean las entradas, mejores serán las variantes de README. Incluye:

• la ruta exacta del archivo fuente
• los locales de destino exactos
• los términos que nunca deben traducirse
• los autónimos preferidos para los nombres de idioma
• si los archivos traducidos existentes deben sobrescribirse o solo actualizarse

Esto reduce el fallo más común: traducción correcta, comportamiento incorrecto dentro del repositorio.

Proporciona un glosario de nombres y términos técnicos

Si tu README contiene nombres de producto, comandos de CLI, nombres de paquetes o terminología específica del dominio, enuméralos explícitamente. readme-i18n ya intenta preservar literales, pero un glosario breve mejora la consistencia en encabezados, descripciones de funcionalidades y ejemplos.

Dile a la skill qué no debe tocar

Una de las mejores formas de mejorar readme-i18n usage es marcar límites duros:

• mantener todos los bloques de código idénticos byte a byte
• conservar los enlaces relativos
• no renombrar archivos salvo que se pida
• no cambiar los destinos de los badges
• no reordenar secciones

Estas instrucciones se alinean de forma muy estrecha con la checklist de preservación y evitan cambios “útiles” que en realidad resultan dañinos.

Revisa la ubicación del selector antes de hacer commit

Un problema habitual en la salida es un selector de idioma incómodo o duplicado. Compara el selector generado con references/language-selector-reference.md y comprueba:

• que solo exista un selector por archivo
• que la ubicación sea consistente entre variantes
• que el idioma actual esté en negrita y no enlazado
• que los enlaces apunten a los nombres de archivo hermanos reales

Es una revisión pequeña con un retorno muy alto.

Comprueba los encabezados localizados y los anchors

Los encabezados traducidos pueden alterar el comportamiento de los anchors generados en plataformas que derivan los fragment IDs del texto del encabezado. La skill intenta conservar la jerarquía de encabezados, pero aun así conviene probar los enlaces internos tras la traducción, especialmente en README largos.

Itera a partir de cambios en el original, no con ediciones ad hoc

Para un mantenimiento a largo plazo, mantén README.md como fuente única de verdad y vuelve a ejecutar readme-i18n a partir de las actualizaciones del original, en vez de editar a mano cada archivo localizado de forma independiente. Así mantendrás alineados con el tiempo el orden de las secciones, el contenido del selector y la terminología.

Usa verificación lado a lado tras la primera ejecución

Después de la primera pasada, compara los archivos de origen y destino para revisar:

• el mismo número de secciones
• el mismo número de bloques de código
• las mismas tablas y estructura de listas
• las mismas imágenes y badges
• enlaces del selector funcionando

Esto detecta regresiones estructurales más rápido que releer cada frase.

Mejora futuras ejecuciones con convenciones explícitas del repositorio

Si tu repositorio tiene un patrón multilingüe no estándar, indícalo directamente en el prompt la próxima vez que invoques readme-i18n. Ejemplos:

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

La skill se vuelve mucho más fiable cuando las convenciones del repositorio se nombran explícitamente en lugar de inferirse.