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