diff --git a/.cspell.yml b/.cspell.yml index e7fec43fa899..1093a17f4591 100644 --- a/.cspell.yml +++ b/.cspell.yml @@ -113,6 +113,7 @@ words: - overridable - outro - packagist + - pageinfo - Paixão - parentbased - Pavol diff --git a/content/en/docs/contributing/localization.md b/content/en/docs/contributing/localization.md new file mode 100644 index 000000000000..dd8e8b3fd464 --- /dev/null +++ b/content/en/docs/contributing/localization.md @@ -0,0 +1,133 @@ +--- +title: Site localization +description: + Guidance on creating and maintaining site page in non-English localizations. +linkTitle: Localization +weight: 20 +--- + +{{% pageinfo color="warning" %}} + +🚧 This DRAFT page is under active development. 🚧 + +{{% /pageinfo %}} + +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 {#track-changes} + +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//page.md`, this +translation is based on a specific [`main` branch commit][main] of the +corresponding English language version of the page at +`content/en//page.md`. Every localized page identifies this commit in +the page's front matter as follows: + +```markdown +--- +title: Your localized page title +... + +## default_lang_commit: +``` + +The front matter above would be in `content/zh//page.md`. The commit +corresponds to the latest commit of `content/en//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: + +```console +$ 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: + +```sh +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: + +```console +$ 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`: + +```sh +scripts/i18n-check.sh -u +``` + +### 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. + +{{% alert title="Tip" %}} + +If your localized page now corresponds to the English language version in `main` +at `HEAD`, then erase the commit hash value in the front matter, and run the +update command given in the previous section to automatically refresh the +`default_lang_commit` field value. + +{{% /alert %}} + +## New localizations + +(Section To Be Completed soon with information about how to propose a new +localization.) + + + +[main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/ +[multilingual framework]: https://gohugo.io/content-management/multilingual/ diff --git a/content/en/docs/zero-code/_index.md b/content/en/docs/zero-code/_index.md index e2c748fc7576..170bea2002bd 100644 --- a/content/en/docs/zero-code/_index.md +++ b/content/en/docs/zero-code/_index.md @@ -1,7 +1,6 @@ --- title: Zero-code Instrumentation weight: 260 -cSpell:ignore: pageinfo --- {{% pageinfo color="warning" %}} diff --git a/scripts/i18n-check.sh b/scripts/i18n-check.sh index e09680d9c380..036d77173fd4 100755 --- a/scripts/i18n-check.sh +++ b/scripts/i18n-check.sh @@ -5,6 +5,7 @@ DEFAULT_LANG="en" DEFAULT_TARGET="content" EXTRA_DIFF_ARGS="--numstat" +FLAG_DIFF_DETAILS="" FLAG_UPDATE="" FLAG_VERBOSE="" I18N_DLC_KEY="default_lang_commit" @@ -42,6 +43,7 @@ function process_CLI_args() { usage ;; d) + FLAG_DIFF_DETAILS=1 EXTRA_DIFF_ARGS="" ;; u) @@ -115,6 +117,10 @@ function main() { # Get commit hash from git commit info LASTCOMMIT=$(git log -n 1 --pretty=format:%h -- "$f") fi + if [[ -z $LASTCOMMIT ]]; then + # Get last commit of `main` that this branch is rooted from. + LASTCOMMIT=$(git merge-base main HEAD) + fi if [[ -n $FLAG_UPDATE ]]; then update_i18n_hash "$LASTCOMMIT" "$f" @@ -128,8 +134,12 @@ function main() { DIFF=$(git diff --exit-code $EXTRA_DIFF_ARGS $LASTCOMMIT...HEAD "$EN_VERSION") if [[ -n "$DIFF" ]]; then # [[ $? -ne 0 ]] - echo "$DIFF - $f" SYNCED=0 + if [[ -n "$FLAG_DIFF_DETAILS" ]]; then + echo -n "$DIFF" + else + echo "$DIFF - $f" + fi elif [[ -n $FLAG_VERBOSE ]]; then echo -e "File is in sync\t$f" fi diff --git a/static/refcache.json b/static/refcache.json index 2f0969ad1a89..9db31093ff58 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -4255,6 +4255,10 @@ "StatusCode": 200, "LastSeen": "2024-01-30T16:15:20.42238-05:00" }, + "https://github.com/open-telemetry/opentelemetry.io/commits/main/": { + "StatusCode": 200, + "LastSeen": "2024-06-06T14:51:54.994687-04:00" + }, "https://github.com/open-telemetry/opentelemetry.io/fork": { "StatusCode": 200, "LastSeen": "2024-01-30T16:15:47.00387-05:00" @@ -4787,6 +4791,10 @@ "StatusCode": 206, "LastSeen": "2024-01-30T16:05:33.151121-05:00" }, + "https://gohugo.io/content-management/multilingual/": { + "StatusCode": 206, + "LastSeen": "2024-06-06T14:51:47.628909-04:00" + }, "https://golang.org/ref/spec#Slice_types": { "StatusCode": 200, "LastSeen": "2024-01-18T19:02:17.04578-05:00"