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

We recommend that you follow the guidance offered in this section when translating pages.

Heading anchors

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

For link references to local paths (as opposed to external links), preserve the path as is. This holds true for links to website pages or section-local resources such as images.

Images

Hugo is smart in the way that it renders page images that are shared across site localizations. That is, in the generated site folder, Hugo will output a single image file that is then shared across localizations.

So as a general rule, do not make copies of image files in your localization unless you actually change the image.

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: <commit-hash-of-main-for-default-language-page>

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

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/kubernetes/_index.md - content/zh/docs/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/kubernetes
diff --git a/content/en/docs/kubernetes/_index.md b/content/en/docs/kubernetes/_index.md
index 3592df5d..c7980653 100644
--- a/content/en/docs/kubernetes/_index.md
+++ b/content/en/docs/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 -u 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>

Script help

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

New localizations

(Section To Be Completed soon with information about how to propose a new localization.)