Site localization

The OTel website uses Hugo’s multilingual framework to support page localizations. English is the default language, with US English as the default (implicit) localization. A growing number of other localizations are supported, as can be seen from the languages dropdown menu in the top nav.

Translation guidance

When translating website pages from English, we recommend that you follow the guidance offered in this section.

Summary

✅ Do

❌ Do NOT

Heading IDs

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.

Links

Do not translate link references. This holds true for external links, and paths to website pages and section-local resources such as 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.

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.