title: Localización del sitio description: Creación y mantenimiento de páginas del sitio en localizaciones que no están en inglés. linkTitle: Localización weight: 25 cSpell:ignore: shortcodes default_lang_commit: f2a520b85d72db706bff91d879f5bb10fd2e7367

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.

Resumen

✅ Hacer

❌ No traducir

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 lo tiene. La sintaxis del ID de encabezado se escribe después del texto del encabezado usando la sintaxis { #un-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 imágenes.

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

Images and diagrams

Do not make copies of image files unless you localize text in the image itself².

Do translate text in Mermaid diagrams.

Include files

Do translate page fragments found under _includes directories just as you would translate any other page content.

Shortcodes

Some of the base shortcodes contain English text that you might need to localize – this is particularly true of those contained in layouts/shortcodes/docs.

If you need to create a localized version of a shortcode, place it under layouts/shortcodes/xx, where xx is your localization’s language code. From there, use the same relative path as the original base shortcode.

Keeping track of localized-page drift

One of the main challenges of maintaining localized pages, is identifying when the corresponding English language pages have been updated. This section explains how we handle this.

The default_lang_commit front-matter field

When a localized page is written, such as content/zh/<some-path>/page.md, this translation is based on a specific main branch commit of the corresponding English language version of the page at content/en/<some-path>/page.md. In this repository, every localized page identifies the English page commit in the localized page’s front matter as follows:

---
title: Your localized page title
# ...
default_lang_commit: <most-recent-commit-hash-of-default-language-page>
---

The front matter above would be in content/zh/<some-path>/page.md. The commit hash would correspond to the latest commit of content/en/<some-path>/page.md from the main branch.

Tracking changes to English pages

As updates are made to English language pages, you can keep track of the corresponding localized pages that need updating by running the following command:

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

You can restrict the target pages to one or more localizations by providing path(s) like this:

npm run check:i18n -- content/zh

Viewing change details

For any given localized pages that need updating, you can see the diff details of the corresponding English language pages by using the -d flag and providing the paths to your localized pages, or omit the paths to see all. For example:

$ 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
 ---

Adding default_lang_commit to new pages

As you create pages for your localization, remember to add default_lang_commit to the page front matter along with an appropriate commit hash from main.

If your page translation is based on an English page in main at <hash>, then run the following command to automatically add default_lang_commit to your page file’s front matter using the commit <hash>. You can specify HEAD as an argument if your pages are now synced with main at HEAD. For example:

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

To list localization page files with missing hash keys, run:

npm run check:i18n -- -n

Updating default_lang_commit for existing pages

As you update your localized pages to match changes made to the corresponding English language page, ensure that you also update the default_lang_commit commit hash.

If you have batch updated all of your localization pages that had drifted, you can update the commit hash of these files using the -c flag followed by a commit hash or ‘HEAD’ to use main@HEAD.

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

Drift status

Run npm run fix:i18n:status to add a front-matter field drifted_from_default to those target localization pages that have drifted. This field will soon be used to display a banner at the top of pages that have drifted relative to their English counterparts.

Script help

For more details about the script, run npm run check:i18n -- -h.

New localizations

To start a new localization for the OpenTelemetry website, raise an issue to share your interest to contribute. Tag all other individuals that are willing to write and review translations in the language you want to add. You need at least two potential contributors, ideally three. Include the following task list in your issue as well:

- [ ] Contributors for the new language: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
- [ ] Localize site homepage to YOUR_LANGUAGE_NAME
- [ ] Create an issue label for `lang:LANG_ID`
- [ ] Create org-level group for `LANG_ID` approvers
- [ ] Update components owners for `content/LANG_ID`
- [ ] Set up spell checking, if a cSpell dictionary is available

Notes:

• For LANG_ID, use an official ISO 639-1 code for the language you want to add.
• Look for cSpell dictionaries available as NPM packages @cspell/dict-LANG_ID. If a dictionary isn’t available for your dialect or region, choose the closest region. For an example of how to set this up, see PR #5386.

After you created that issue and have the required amount of contributors, maintainers will ask you to provide a pull request with a translation of the index page. Make sure that maintainers are allowed to edit your PR, since they will add additional changes to your PR that are required to get your localization project started.

With your first PR merged maintainers will take care of setting up the issue label, the org-level group and the component owners.

English-language maintainer guidance

When link checking fails for non-English pages

English is the default language of the OpenTelemetry website. After you add, edit, or reorganized English language documentation, link checking may fail for non-English pages. When this happens:

• Do not fix the broken links. Each non-English page is associated with a specific commit of the corresponding English page, as identified by the git commit hash value of the default_lang_commit front matter key.
• Configure the link checker to ignore the non-English pages by adding the following to the page’s front matter, or to the closest common ancestor file, when more than one page has link errors:

  htmltest:
    # TODO: remove the IgnoreDirs once broken links are fixed
    IgnoreDirs:
      - path-regex/to/non-en/directory/contain/files/to/ignore
      - path-2-etc
  

• Run npm run check:links and include any updates to the .htmltest.yml config file with your PR.