[CI & i18n] i18n script and doc improvements (#4648)

.github/workflows/check-i18n.yml

@@ -4,12 +4,15 @@ on:
   pull_request:
 
 jobs:
-  i18n-check:
+  check-i18n:
     name: I18N check
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # all
-      - run: scripts/i18n-check.sh -u
-      - run: .github/workflows/scripts/i18n-check-helper.sh
+      - name: Any files missing hash key?
+        run: scripts/check-i18n.sh -n -x -v
+      - name: Any files with invalid hash keys?
+        run: scripts/check-i18n.sh -v
+      - run: .github/workflows/scripts/check-i18n-helper.sh

.github/workflows/scripts/i18n-check-helper.sh → .github/workflows/scripts/check-i18n-helper.sh

@@ -10,12 +10,12 @@ if [[ -z $CHANGES ]]; then
 fi
 
 cat <<EOS
-Some i18n pages are missing the 'default_lang_commit' front matter field.
-To fix this in your local development environment, run
+Some localization pages are missing the 'default_lang_commit' front matter
+field. To fix this in your local development environment, run
 
-    scripts/i18n-check.sh -u
+    npm run fix:i18n:new
 
-and commit the changes for your locale. Here are the list of pages that
+and commit the changes for your localization. Here are the list of pages that
 need to be updated:
 ---
 EOS

content/en/docs/contributing/localization.md

@@ -19,7 +19,7 @@ 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
+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.
 
@@ -28,19 +28,21 @@ explains how we handle this.
 When a localized page is written, such as `content/zh/<some-path>/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/<some-path>/page.md`. Every localized page identifies this commit in
-the page's front matter as follows:
+`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:
 
 ```markdown
 ---
 title: Your localized page title
 ...
 
-## default_lang_commit: <commit-hash-of-main-for-default-language-page>
+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`.
+would correspond to the latest commit of `content/en/<some-path>/page.md` in
+`main`.
 
 ### Tracking changes to English pages
 
@@ -49,25 +51,26 @@ corresponding localized pages that need updating by running the following
 command:
 
 ```console
-$ scripts/i18n-check.sh
+$ npm run check:i18n
 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:
+You can restrict the target pages to one or more localizations by providing
+path(s) like this:
 
 ```sh
-scripts/i18n-check.sh content/zh
+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. For example:
+the paths to your localized pages, or omit the paths to see all. For example:
 
 ```console
-$ scripts/i18n-check.sh -d content/zh/docs/kubernetes
+$ 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
@@ -87,12 +90,20 @@ index 3592df5d..c7980653 100644
 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`:
+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:
 
 ```sh
-scripts/i18n-check.sh -u <PATH-TO-YOUR-NEW-FILES>
+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:
+
+```sh
+npm run check:i18n -- -n
 ```
 
 ### Updating `default_lang_commit` for existing pages
@@ -105,11 +116,32 @@ commit hash.
 
 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
+**add** command given in the previous section to automatically refresh the
 `default_lang_commit` field value.
 
 {{% /alert %}}
 
+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`.
+
+```sh
+npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
+npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>
+```
+
+{{% alert title="Important" %}}
+
+When you use `HEAD` 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.
+
+{{% /alert %}}
+
+### 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

package.json

@@ -41,6 +41,7 @@
     "cd:public": "cd public &&",
     "check:filenames": "test -z \"$(npm run -s _ls-bad-filenames)\" || npm run -s _filename-error",
     "check:format": "npm run _check:format && npm run _check:format:ja+zh || (echo '[help] Run: npm run fix:format'; exit 1)",
+    "check:i18n": "scripts/check-i18n.sh",
     "check:links:internal": "npm run _check:links:internal",
     "check:links": "npm run _check:links",
     "check:markdown": "scripts/check-markdown-wrapper.sh",
@@ -58,7 +59,10 @@
     "fix:dict": "find content layouts -name \"*.md\" -print0 | xargs -0 scripts/normalize-cspell-front-matter.pl",
     "fix:filenames": "npm run _rename-to-kebab-case",
     "fix:format": "npm run format",
-    "fix:i18n": "scripts/i18n-check.sh -u",
+    "fix:i18n:all": "scripts/check-i18n.sh -a -c HEAD",
+    "fix:i18n:drifted": "scripts/check-i18n.sh -c HEAD",
+    "fix:i18n:new": "scripts/check-i18n.sh -n -c HEAD",
+    "fix:i18n": "npm run fix:i18n:new",
     "fix:markdown": "npm run check:markdown -- --fix",
     "fix:refcache": "npm run check:links",
     "fix:submodules": "npm run _sync",