Site localization

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

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. Every localized page identifies this commit in the 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 corresponds 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:

$ scripts/i18n-check.sh
1       1       content/en/docs/kubernetes/_index.md - content/zh/docs/kubernetes/_index.md
...

Specify the path to your localization to restrict the output, for example:

scripts/i18n-check.sh 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. For example:

$ scripts/i18n-check.sh -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 translation is based on an English page in main at HEAD, then run the following command to automatically add default_lang_commit to your page file’s front matter using the commit hash at HEAD:

scripts/i18n-check.sh -u <PATH-TO-YOUR-NEW-FILES>

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.

New localizations

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