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.
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_commitfront 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:linksand include any updates to the.htmltest.ymlconfig file with your PR.
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.
Note
We leave it to the discretion of localization authors to decide if they add an explicit heading ID to all headings of translated pages, or whether this is only done for known intra-site heading targets, as reported by the link checker. The former option is more uniform and more work. It better supports having site-external targets into localization pages and avoids having to revisit previously translated pages as new heading targets are used.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.
Note
The OTel website repository has a custom render-link hook that Hugo uses to convert absolute link paths 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.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.
Tip
If your localized page now corresponds to the English language version inmain
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.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>
Important
When you useHEAD 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.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.
Important
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 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.
When starting the localization project, maintainers will treat your reviews as if you are an approver already.
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!