feat: [es] New translation - docs/contributing/localization

Signed-off-by: carolina valencia <krol3@users.noreply.github.com>

Author: krol3

content/es/docs/contributing/localization.md

@@ -0,0 +1,332 @@
+---
+title: Localización del sitio
+description:
+  Creación y mantenimiento de páginas del sitio en localizaciones no inglesas.
+linkTitle: Localización
+weight: 25
+cSpell:ignore: shortcodes
+default_lang_commit: 56dcd5a47eba51a1a2bed49db83a460a1a8d8a06
+---
+
+El sitio web de OTel utiliza el
+[framework multilingüe](https://gohugo.io/content-management/multilingual/) 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, recomendamos seguir la guía
+ofrecida en esta sección.
+
+### Resumen / TL;DR {#summary}
+
+Traducir:
+
+- Los campos de [Front matter][] `title`, `linkTitle` y `description`.
+- El contenido de la página, incluidos los campos de texto en los
+  [diagramas](#images) de Mermaid.
+
+**No** traducir:
+
+- Traducir:
+  - Nombres de **archivos o directorios** de recursos en este repositorio.
+  - [Enlaces](#links), esto incluye los [IDs de encabezado](#headings).[^*]
+  - Campos de [Front matter][] distintos a los mencionados en la sección
+    "Traducir" anterior. En particular, no traduzcas `aliases`. En caso de duda,
+    consulta con los mantenedores.
+- Crear **copias de imágenes**, a menos que
+  [localices el texto dentro de las imágenes](#images).
+
+[^*]: Para una posible excepción, consulta [Enlaces](#links).
+
+### Heading IDs {#headings}
+
+To ensure that heading anchor targets are uniform across localizations, when
+translating headings:
+
+- Preserve the heading's explicit ID if it has one. [Heading ID syntax][] is
+  written after the heading text using syntax like `{ #some-id }`.
+- Otherwise, explicitly declare a heading ID corresponding to the autogenerated
+  ID of the original English heading.
+
+[Heading ID syntax]:
+  https://github.com/yuin/goldmark/blob/master/README.md#headings
+
+### Links {#links}
+
+Do **not** translate link references. This holds true for external links, and
+paths to website pages and section-local resources such as [images](#images).
+
+The only exception is for links to external pages (such as
+<https://en.wikipedia.org>) that have a version specific to your local. Often
+this means replacing the `en` in the URL by your locale's language code.
+
+{{% alert title="Note" %}}
+
+The OTel website repository has a custom render-link hook that Hugo uses to
+convert absolute link paths referring to documentation pages. **Links of the
+form `/docs/some-page` are made locale specific** by prefixing the path with the
+page language code when rendering the link. For example, the previous sample
+path would become `/ja/docs/some-page` when rendered from a Japanese page.
+
+{{% /alert %}}
+
+### Images and diagrams {#images}
+
+Do **not** make copies of image files unless you localize text in the image
+itself[^shared-images].
+
+**Do** translate text in [Mermaid][] diagrams.
+
+[^shared-images]:
+    Hugo is smart about the way that it renders image files that are shared
+    across site localizations. That is, Hugo will output a _single_ image file
+    and share it across locales.
+
+[Mermaid]: https://mermaid.js.org
+
+### Include files {#includes}
+
+**Do** translate page fragments found under `_includes` directories just as you
+would translate any other page content.
+
+### Shortcodes
+
+{{% alert title="Note" %}}
+
+As of February 2025, we are in the process of migrating from shortcodes to
+[include files](#includes) as a means of supporting shared-page content.
+
+{{% /alert %}}
+
+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.
+
+[layouts/shortcodes/docs]:
+  https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs
+
+## Keeping track of localized-page drift {#track-changes}
+
+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][main] 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:
+
+```markdown
+---
+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:
+
+```console
+$ 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:
+
+```sh
+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:
+
+```console
+$ 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:
+
+```sh
+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:
+
+```sh
+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.
+
+{{% alert title="Tip" %}}
+
+If your localized page now corresponds to the English language version in `main`
+at `HEAD`, then erase the commit hash value in the front matter, and run the
+**add** command given in the previous section to automatically refresh the
+`default_lang_commit` field value.
+
+{{% /alert %}}
+
+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`.
+
+```sh
+npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
+npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>
+```
+
+{{% alert title="Important" %}}
+
+When you use `HEAD` as a hash specifier, the script will use the hash of `main`
+at HEAD in your **local environment**. Make sure that you fetch and pull `main`,
+if you want HEAD to correspond to `main` in GitHub.
+
+{{% /alert %}}
+
+### 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](https://github.com/open-telemetry/opentelemetry.io/issues/) 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:
+
+```markdown
+- [ ] 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](https://en.wikipedia.org/wiki/ISO_639-1) for the language you
+  want to add.
+- Look for
+  [cSpell dictionaries](https://github.com/streetsidesoftware/cspell-dicts)
+  available as NPM packages
+  [@cspell/dict-LANG_ID](https://www.npmjs.com/search?q=%40cspell%2Fdict). 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](https://github.com/open-telemetry/opentelemetry.io/blob/main/content/en/_index.md).
+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.
+
+{{% alert title="Important" color="warning" %}}
+
+You don't have to be an existing contributor to the OpenTelemetry project, to
+start a new localization. However you will not be added as a member of the
+[OpenTelemetry GitHub organization](https://github.com/open-telemetry/) or as a
+member of the approvers group for your localization. You will need to satisfy
+the requirements for becoming an established member and approver as outlined in
+the
+[membership guidelines](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md).
+
+When starting the localization project, maintainers will treat your reviews as
+if you are an approver already.
+
+{{% /alert %}}
+
+## 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:
+
+<!-- markdownlint-disable blanks-around-fences -->
+
+- 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:
+  ```yaml
+  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.
+
+<!-- markdownlint-enable blanks-around-fences -->
+
+[front matter]: https://gohugo.io/content-management/front-matter/
+[main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/
+[multilingual framework]: https://gohugo.io/content-management/multilingual/
+[PR #5386]: https://github.com/open-telemetry/opentelemetry.io/pull/5386/files