mikaellolbatera159-stack/localizations

Localizar contenido en los idiomas especificados

Una habilidad que localiza contenido en los idiomas especificados.

Cómo funciona

La habilidad toma contenido de entrada y una lista de idiomas objetivo. Luego traduce el contenido a cada idioma especificado, proporcionando versiones localizadas para cada uno.

Estructura del contenido

.
└── docs/                         ← contenido del taller (fuente + resultados localizados)
    ├── README.md                 ← página de inicio (fuente; slug: index)
    ├── <categoría>/             ← categoría del taller en inglés
    │   ├── README.md             ← inicio de categoría (fuente; slug: <categoría>)
    │   └── <taller>/
    │       ├── README.md         ← inicio del taller (fuente; slug: <categoría>/<taller>)
    │       └── *.md
    ├── _images/              ← recursos compartidos (no se localizan)
    └── <idioma>/             ← salida localizada, hijo directo de docs/
        ├── README.md         ← inicio del idioma (slug: <idioma>)
        └── <categoría>/
            ├── README.md         ← inicio de categoría localizado (slug: <idioma>/<categoría>)
            └── <taller>/
                ├── README.md     ← inicio del taller localizado (slug: <idioma>/<categoría>/<taller>)
                └── *.md

Contenido de entrada

Estos son los contenidos que se localizarán:

• Todos los archivos Markdown en inglés bajo docs/ y sus subdirectorios: la página de inicio del sitio (docs/README.md), las páginas de inicio de categorías y las lecciones del taller (docs/<categoría>/<taller>/**/*.md).

No trates _images/ (recursos compartidos) ni ningún directorio raíz de idioma configurado como entrada fuente.

Los archivos que ya están bajo docs/<idioma>/ son salidas, no entradas; nunca trates los directorios raíz de idiomas configurados como contenido fuente para volver a localizar.

Idiomas objetivo

Los idiomas objetivo se definen en el directorio rules como archivos Markdown en esta habilidad (rules/ko-kr.md, por ejemplo). Para determinar qué idiomas procesar, lista los archivos en rules/: cada archivo <idioma>.md corresponde exactamente a un idioma objetivo compatible. Cada idioma tiene su propio conjunto de reglas y pautas para la traducción, asegurando que el contenido localizado sea apropiado para la audiencia objetivo.

Los identificadores de idioma usan minúsculas con un guion (por ejemplo, ko-kr). Esta es la ortografía canónica tanto para el nombre del archivo de reglas como para el directorio de salida en esta habilidad; mantenlos consistentes.

Contenido de salida

Todo el contenido del taller localizado se almacena directamente bajo el directorio de contenido docs/ en la raíz del repositorio, con cada idioma teniendo su propio subdirectorio. Por ejemplo, el contenido en coreano se almacena en docs/ko-kr/.

Los directorios de idiomas deben ser hijos directos de docs/ para que Starlight (configurado en website/astro.config.mjs) los reconozca y renderice su selector de idioma. No añadas un directorio intermedio localizations/.

Proceso de localización

Hay tres casos para la localización. Para detectar cuál aplica, compara el árbol fuente con el árbol existente docs/<idioma>/, y usa el historial git de los archivos fuente para detectar cambios:

• Original existe, no hay versión localizada para el idioma: Crea un nuevo documento localizado.
• Existen tanto el original como la versión localizada: Compara el árbol fuente con docs/<idioma>/, luego ejecuta git diff (o git log) en el archivo fuente para encontrar qué cambió desde que se produjo la última versión localizada. Actualiza solo las secciones afectadas del documento localizado; no retraduzcas secciones sin cambios innecesariamente.
• Existe versión localizada, pero el original ha sido eliminado: Elimina el documento localizado huérfano (y elimina los subdirectorios de idiomas ahora vacíos).

El proceso se ejecuta en dos pasos. Primero, el contenido se analiza para identificar frases clave y contexto. Luego, el agente translator realiza la localización inicial, seguida de un paso de revisión y refinamiento por parte del agente evaluator para asegurar calidad y consistencia.

Los "agentes" translator y evaluator son roles/personas, no herramientas externas. Si no hay subagentes dedicados disponibles, actúalos como personas secuenciales: primero adopta el rol de traductor para producir el borrador, luego adopta el rol de evaluador para criticar y refinar ese borrador según las reglas del idioma. Repite el ciclo de refinamiento hasta que se cumplan los criterios del evaluador.

Preservación de Markdown y formato

Independientemente del idioma, lo siguiente debe preservarse exactamente y no traducirse:

• Las claves del frontmatter YAML (traduce solo los valores donde sea apropiado, por ejemplo, un title). Excepción: la clave slug en las páginas de inicio (README.md): el sitio enruta cada inicio de carpeta mediante su slug, por lo que una página de inicio localizada debe llevar un slug prefijado con el idioma en lugar del inglés. Reescríbelo: una raíz de idioma (docs/<idioma>/README.md) usa slug: <idioma>, una página de inicio de categoría localizada usa slug: <idioma>/<categoría>, y una página de inicio de taller localizada usa slug: <idioma>/<categoría>/<taller>. Nunca copies un slug de inicio en inglés textualmente a un archivo localizado porque colisionaría con la ruta en inglés.
• Código delimitado y en línea, incluyendo nombres de variables, funciones y comandos.
• URLs y destinos de enlaces externos.
• Etiquetas HTML, estructura Markdown, tablas y marcadores de admoniciones.

Traduce el texto en lenguaje humano, incluyendo comentarios dentro de bloques de código donde sean explicativos (según las reglas del idioma). Mantén el orden de los encabezados y la estructura del documento estable.

Los anclajes de encabezado siguen al texto localizado. Cuando se traduce un encabezado, su anclaje/slug generado automáticamente cambia con él; esto es esperado. El requisito es que los enlaces de anclaje dentro del mismo documento sigan resolviéndose: cada vez que traduzcas un encabezado, actualiza cada enlace dentro de la página que lo apunte (](#...)) al nuevo slug del encabezado localizado. No dejes un enlace apuntando al slug en inglés original una vez que el encabezado está traducido, y no preserves un anclaje en inglés que ya no coincida con su encabezado. Los anclajes que apunten a archivos no localizados (o URLs externas) mantienen su destino original.

Las rutas de imágenes y recursos apuntan a los recursos originales a menos que exista un recurso localizado. Debido a que los archivos localizados están bajo docs/<idioma>/, reescribe las rutas relativas según sea necesario para que sigan resolviendo al recurso compartido (por ejemplo, una lección en docs/<idioma>/real-world-development/app/2-foo.md usa ../../../_images/x.png para llegar a docs/_images/). Solo apunta a un recurso localizado cuando exista una imagen traducida correspondiente bajo el árbol del idioma. De cualquier manera, el enlace debe resolverse a un archivo real.

Agente traductor

Usa el agente translator para realizar la localización. Debe seguir las reglas y pautas definidas para cada documento de idioma objetivo en el directorio rules.

Agente evaluador

Usa el agente evaluator para evaluar la calidad del contenido localizado. El evaluador verifica la precisión, la relevancia cultural y la calidad general, siguiendo las reglas y pautas definidas para el idioma objetivo en el directorio rules.

El evaluador puntúa el documento localizado contra la Rúbrica de puntuación del evaluador del idioma (definida en rules/<idioma>.md del idioma). La rúbrica usa dos niveles: Nivel A con criterios de fallo duro que deben obtener 5, y Nivel B con criterios graduados (1–5) que deben obtener 4 o 5. Un documento pasa solo cuando cada criterio aplicable del Nivel A obtiene 5 y cada criterio aplicable del Nivel B obtiene ≥ 4. Si algo no alcanza, devuelve el documento al traductor con notas específicas y vuelve a ejecutar el ciclo traducir → evaluar hasta que pase, escalando a un humano después del límite de iteraciones de la rúbrica.

QUÉ HACER Y QUÉ NO HACER

• Sí: Realiza la localización solo para los idiomas objetivo definidos en el directorio rules (un <idioma>.md por idioma compatible). No localices en idiomas no compatibles.
• Sí: Preserva la estructura Markdown, el código, los destinos de enlaces/URL externos y las claves del frontmatter exactamente (ver Preservación de Markdown y formato).
• Sí: Deja que los anclajes de encabezado sigan el texto del encabezado localizado, y actualiza los enlaces de anclaje dentro del mismo documento para que coincidan con los nuevos slugs y sigan resolviéndose (ver Preservación de Markdown y formato).
• Sí: Apunta las rutas de imágenes y recursos a los recursos originales (reescribiendo la ruta relativa según sea necesario para que se resuelva desde docs/<idioma>/), a menos que exista un recurso localizado correspondiente (ver Preservación de Markdown y formato).
• Sí: Refleja la estructura del directorio fuente bajo docs/<idioma>/.
• No: Trates los directorios raíz de idiomas configurados como entrada fuente.
• No: Reordenes o reestructures el contenido; mantén los encabezados y su orden estables.
• No: Traduzcas código, comandos o identificadores; traduce solo prosa explicativa y comentarios de código.