Localización del sitio

El sitio web de OTel utiliza el framework multilingüe de Hugo para soportar la localización de páginas. El inglés es el idioma predeterminado, con inglés estadounidense como la localización predeterminada (implícita). Se admite un número creciente de otras localizaciones, como se puede ver en el menú desplegable de idiomas en la barra de navegación superior.

Guía de traducción

Al traducir páginas del sitio web desde el inglés, te recomendamos seguir las instrucciones que se ofrecen en esta sección.

Resumen

✅ Hacer

❌ No hacer

IDs de encabezados

Para garantizar que los anclajes de los encabezados sean uniformes en todas las localizaciones, al traducir encabezados:

• Conserva el ID explícito del encabezado si ya lo tiene. La sintaxis de ID de encabezado se escribe después del texto del encabezado usando una sintaxis como { #algún-id }.
• De lo contrario, declara explícitamente un ID de encabezado que corresponda al ID autogenerado del encabezado original en inglés.

Enlaces

No traduzcas las referencias de enlaces. Esto aplica tanto para enlaces externos como para rutas a páginas del sitio web y recursos locales de la sección, como las imágenes.

La única excepción son los enlaces a páginas externas (como https://en.wikipedia.org) que tienen una versión específica para tu idioma local. A menudo, esto implica reemplazar el en en la URL por el código de idioma correspondiente a tu localidad.

Etiquetas de definición de enlaces

Los autores de localizaciones pueden optar por traducir o no las etiquetas de las definiciones de enlaces en Markdown. Si eliges mantener la etiqueta en inglés, sigue las instrucciones de esta sección.

Por ejemplo, considera el siguiente Markdown:

[Hello], world! Welcome to the [OTel website][].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

Esto se traduciría al francés como:

[Bonjour][hello], le monde! Bienvenue sur le [site OTel][OTel website].

[hello]: https://code.org/helloworld
[OTel website]: https://opentelemetry.io

Imágenes y diagramas

No hagas copias de archivos de imagen a menos que localices el texto dentro de la propia imagen².

Sí debes traducir el texto en los diagramas de Mermaid.

Archivos incluidos

Sí debes traducir los fragmentos de página ubicados en los directorios _includes, tal como traducirías cualquier otro contenido de la página.

Shortcodes

Algunos de los shortcodes base contienen texto en inglés que podrías necesitar localizar, especialmente aquellos que se encuentran en layouts/_shortcodes/docs.

Si necesitas crear una versión localizada de un shortcode, colócala en layouts/_shortcodes/xx, donde xx es el código de idioma de tu localización. A partir de ahí, utiliza la misma ruta relativa que el shortcode base original.

Seguimiento de cambios en páginas localizadas

Uno de los principales desafíos al mantener páginas localizadas es identificar cuándo se han actualizado las páginas correspondientes en inglés. Esta sección explica cómo manejamos ese proceso.

El campo default_lang_commit en el front matter

Cuando se escribe una página localizada, como content/zh/<some-path>/page.md, esta traducción se basa en un commit específico de la rama main de la versión en inglés correspondiente de la página ubicada en content/en/<some-path>/page.md.

En este repositorio, cada página localizada identifica el commit de la página en inglés en el front matter de la página localizada de la siguiente manera:

---
title: Título de la página localizada
# ...
default_lang_commit: <most-recent-commit-hash-of-default-language-page>
---

El front matter anterior se encontraría en content/zh/<some-path>/page.md. El hash del commit correspondería al último commit de content/en/<some-path>/page.md en la rama main.

Seguimiento de cambios en las páginas en inglés

A medida que se realizan actualizaciones en las páginas en inglés, puedes hacer seguimiento de las páginas localizadas que necesitan ser actualizadas ejecutando el siguiente comando:

$ npm run check:i18n
1       1       content/en/docs/platforms/kubernetes/_index.md - content/zh/docs/platforms/kubernetes/_index.md
...

Puedes restringir las páginas objetivo a una o más localizaciones proporcionando rutas como esta:

npm run check:i18n -- content/zh

Ver detalles de los cambios

Para cualquier página localizada que necesite ser actualizada, puedes ver los detalles del diff de las páginas correspondientes en inglés usando la opción -d y proporcionando las rutas a tus páginas localizadas, o puedes omitir las rutas para ver todas. Por ejemplo:

$ npm run check:i18n -- -d content/zh/docs/platforms/kubernetes
diff --git a/content/en/docs/platforms/kubernetes/_index.md b/content/en/docs/platforms/kubernetes/_index.md
index 3592df5d..c7980653 100644
--- a/content/en/docs/platforms/kubernetes/_index.md
+++ b/content/en/docs/platforms/kubernetes/_index.md
@@ -1,7 +1,7 @@
 ---
 title: OpenTelemetry with Kubernetes
 linkTitle: Kubernetes
-weight: 11
+weight: 350
 description: Using OpenTelemetry with Kubernetes
 ---

Agregar default_lang_commit a nuevas páginas

Cuando crees páginas para tu localización, recuerda agregar default_lang_commit al front matter de la página junto con el hash de commit correspondiente desde la rama main.

Si tu traducción se basa en una página en inglés de main en el commit <hash>, puedes ejecutar el siguiente comando para agregar automáticamente default_lang_commit al front matter del archivo de tu página usando ese <hash>.

También puedes usar HEAD como argumento si tus páginas están sincronizadas con main en HEAD. Por ejemplo:

npm run check:i18n -- -n -c 1ca30b4d content/ja
npm run check:i18n -- -n -c HEAD content/zh/docs/concepts

Para listar los archivos de páginas localizadas que no tienen el campo de hash (default_lang_commit), ejecuta:

npm run check:i18n -- -n

Actualización de default_lang_commit en páginas existentes

Al actualizar tus páginas localizadas para que coincidan con los cambios realizados en la página correspondiente en inglés, asegúrate de actualizar también el hash de commit default_lang_commit.

Si has actualizado en lote todas tus páginas localizadas que se habían desincronizado, puedes actualizar el hash de commit de estos archivos usando la opción -c seguida de un hash de commit o de HEAD para usar main@HEAD.

npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>

Estado de desfase

Ejecuta npm run fix:i18n:status para agregar un campo en el front matter llamado drifted_from_default a las páginas de localización objetivo que se hayan desincronizado. Este campo pronto se usará para mostrar un banner en la parte superior de las páginas que estén desincronizadas respecto a sus equivalentes en inglés.

Ayuda del script

Para más detalles sobre el script, ejecuta npm run check:i18n -- -h.

Nuevas localizaciones

¿Te interesa iniciar una nueva localización del sitio web de OTel? Contacta a los mantenedores para expresar tu interés, por ejemplo, a través de una discusión en GitHub o del canal de Slack #otel-docs-localization. Esta sección explica los pasos necesarios para iniciar una nueva localización.

1. Formar un equipo de localización

Crear una localización consiste en hacer crecer una comunidad activa y solidaria. Para iniciar una nueva localización del sitio web de OpenTelemetry necesitas:

1. Un mentor de localización que conozca bien tu idioma, como un aprobador activo del Glosario CNCF o del sitio web de Kubernetes.
2. Al menos dos colaboradores potenciales.

2. Inicio de la localización: crear un issue

Con el equipo de localización listo o en proceso de formación, crea un issue con la lista de tareas indicada a continuación:

1. Busca el código oficial ISO 639-1 del idioma que quieres agregar. Nos referiremos a este código de idioma como LANG_ID en el resto de esta sección. Si tienes dudas sobre qué etiqueta usar, especialmente cuando se trate de elegir una subregión, consulta con los mantenedores.

2. Identifica los usuarios de GitHub del mentor y colaboradores potenciales.

3. Crea un nuevo issue con la siguiente lista de tareas en el comentario inicial:

   - [ ] Language info:
     - ISO 639-1 language code: `LANG_ID`
     - Language name: ADD_NAME_HERE
   - [ ] Locale team info:
     - [ ] Locale mentor: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
     - [ ] Contributors: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
   - [ ] Read through
         [Localization](https://opentelemetry.io/docs/contributing/localization/)
         and all other pages in the Contributing section
   - [ ] Localize site homepage (only) to YOUR_LANGUAGE_NAME and submit a PR.
         For details, see
         [Localize the homepage](https://opentelemetry.io/docs/contributing/localization/#homepage).
   - [ ] OTel maintainers:
     - [ ] Update Hugo config for `LANG_ID`
     - [ ] Configure cSpell and other tooling support
     - [ ] Create an issue label for `lang:LANG_ID`
     - [ ] Create org-level group for `LANG_ID` approvers
     - [ ] Update components owners for `content/LANG_ID`
   - [ ] Create an issue to track the localization of the **glossary**. Add the
         issue number here. For details, see
         [Localize the glossary](https://opentelemetry.io/docs/contributing/localization/#glossary).
   

3. Localizar la página principal

Envía un pull request con la traducción de la página principal del sitio web, y nada más, en el archivo content/LANG_ID/_index.md. Asegúrate de que los mantenedores tengan los permisos necesarios para editar tu PR, ya que ellos agregarán cambios adicionales necesarios para iniciar tu proyecto de localización.

Después de que tu primer PR sea fusionado, los mantenedores configurarán la etiqueta del issue, el grupo a nivel de organización y los responsables del componente.

4. Localizar el glosario

La segunda página a localizar es el Glosario. Esta es una página crítica para los lectores de las versiones localizadas, ya que define los términos clave utilizados en observabilidad y OpenTelemetry en particular. Esto es especialmente importante si dichos términos no existen en tu idioma.

Para obtener orientación, consulta el video de la charla de Ali Dowair en Write the Docs 2024: El arte de la traducción: Cómo localizar contenido técnico.

5. Localizar las páginas restantes del sitio en incrementos pequeños

Con la terminología establecida, ahora puedes localizar las páginas restantes del sitio.

Lista de verificación para mantenedores de OTel

Hugo

Actualiza la configuración de Hugo para LANG_ID. Agrega las entradas correspondientes para LANG_ID bajo:

• languages en config/_default/hugo.yaml
• module.mounts a través de config/_default/module-template.yaml. Como mínimo, agrega una única entrada de source-target para content. Considera agregar entradas para las páginas de fallback en en solo cuando la localización tenga suficiente contenido.

Ortografía

Busca los diccionarios cSpell disponibles como paquetes NPM @cspell/dict-LANG_ID. Si no hay un diccionario disponible para tu dialecto o región, elige el que corresponda a la región más cercana.

Si no existe un diccionario disponible, entonces omite el resto de esta subsección. De lo contrario:

• Agrega el paquete NPM como dependencia de desarrollo, por ejemplo: npm install --save-dev @cspell/dict-bn.
• Crea .cspell/LANG_ID-words.txt como el archivo de palabras para el diccionario local del sitio para LANG_ID.
• En .cspell.yml, añade entradas para:
  • import
  • dictionaryDefinitions
  • dictionaries: agrega dos entradas aquí, una para LANG_ID y otra para LANG_ID-words.txt

Soporte para otras herramientas

• Soporte para Prettier: si LANG_ID no está bien soportado por Prettier, agrega reglas de exclusión en .prettierignore

Guía para aprobadores y mantenedores

Los PRs con cambios semánticos no deben abarcar varios locales

Los aprobadores deben asegurar que los PRs que realicen cambios semánticos en las páginas de documentación no abarquen múltiples locales. Un cambio semántico es aquel que impacta el significado del contenido de la página. Nuestro proceso de localización de documentación asegura que los aprobadores de cada locale, a su debido tiempo, revisen las ediciones en inglés para determinar si los cambios son apropiados para su locale y cómo incorporarlos de la mejor manera. Si se requieren cambios, los aprobadores del locale los harán mediante sus propios PRs específicos del locale.

Los cambios puramente editoriales entre locales están permitidos

Las actualizaciones de páginas puramente editoriales son cambios que no afectan el contenido existente y pueden abarcar múltiples locales. Estos incluyen:

• Mantenimiento de enlaces: Corregir rutas de enlaces rotos cuando las páginas se mueven o eliminan.
• Actualización de recursos: Actualizar enlaces a recursos externos que se hayan movido.
• Adiciones de contenido específico: Agregar nuevas definiciones o secciones específicas a archivos que han divergido, cuando actualizar el archivo completo no sea factible.

Corrección de enlaces y actualización de recursos

Por ejemplo, a veces los cambios en la documentación en inglés pueden provocar fallos en la verificación de enlaces para locales que no están en inglés. Esto sucede cuando las páginas de documentación se mueven o eliminan.

En tales situaciones, realiza las siguientes actualizaciones en cada página no inglesa cuyo enlace falle en la verificación:

• Actualiza la referencia del enlace con la nueva ruta de la página.
• Agrega el comentario YAML # patched al final de la línea del campo default_lang_commit en el front matter.
• No realices ningún otro cambio en el archivo.
• Vuelve a ejecutar npm run check:links y asegúrate de que no queden fallos de enlaces.

Cuando un enlace externo a un recurso movido (pero semánticamente sin cambios) (como un archivo de GitHub) resulte en un fallo de verificación de enlaces, considera:

• Eliminar el enlace roto del refcache
• Actualizar el enlace en todos los locales usando el método descrito anteriormente en esta sección.

Adiciones de contenido específico a archivos divergentes

Cuando agregues contenido nuevo específico a un archivo localizado que ha divergido de la versión en inglés, puedes optar por hacer una actualización específica en lugar de actualizar el archivo completo. Por ejemplo, cuando se agrega un nuevo término de glosario como “cardinalidad” al glosario en inglés, puedes agregar solo ese término al glosario localizado sin abordar otro contenido divergente.

Aquí hay un ejemplo del flujo de trabajo para esta actualización específica:

• Agrega solo el bloque de definición de “cardinalidad” al archivo de glosario localizado
• Actualiza el front matter agregando # patched como comentario al final de la línea default_lang_commit
• Deja todo el contenido existente sin cambios
• En la descripción del PR, documenta claramente:
  • El contenido específico agregado (definición de “cardinalidad”)
  • Que el archivo sigue divergente en otro contenido
  • La justificación de la actualización específica (por ejemplo, “Proporcionar nueva terminología crítica a los lectores localizados sin requerir sincronización completa del archivo”)

Este enfoque permite mejoras incrementales al contenido localizado mientras se mantiene la conciencia de que el archivo aún requiere atención futura para una sincronización completa con la versión en inglés.