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

No traduzcas las etiquetas de las definiciones de enlaces en Markdown. En su lugar, reescribe la etiqueta como texto traducido del enlace. Por ejemplo, considera el siguiente Markdown:

[Hola], mundo! Bienvenido al [sitio de OTel][].

[hola]: https://code.org/helloworld
[sitio de OTel]: 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 “Drift status”

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

Nuevo equipo de localización

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.

Una vez que estés listo:

1. Crea un nuevo issue para compartir tu interés en contribuir.

2. Añade los usuarios de GitHub del mentor y de los colaboradores potenciales.

3. 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.

4. Añade la siguiente lista de tareas al comentario inicial de tu issue:

   - [ ] 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 to YOUR_LANGUAGE_NAME
   - [ ] OTel maintainers:
     - [ ] Update `hugo.yaml`
     - [ ] 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`
   

5. Envía un pull request con la traducción de la página principal del sitio web homepage, 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.

Lista de verificación para mantenedores de OTel

Hugo

Actualiza hugo.yaml. Agrega las entradas correspondientes para LANG_ID bajo:

• languages
• module.mounts. 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 mantenedores del idioma inglés

Evitar PRs con cambios en la documentación que abarquen varios locales

Los colaboradores deben evitar enviar PRs que realicen cambios en la documentación que afecten a varios locales. La única excepción está documentada en la siguiente sección.

Cuando falla la verificación de enlaces en páginas que no están en inglés

A veces, los cambios en la documentación en inglés pueden provocar fallos en la verificación de enlaces para locales no ingleses. 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.