[i18n] Update localization guidance (#6408)

Author: chalin

content/en/docs/contributing/localization.md

@@ -11,90 +11,89 @@ 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
+## Translation guidance
 
-### When link checking fails for non-English pages
+When translating website pages from English, we recommend that you follow the
+guidance offered in this section.
 
-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:
+### Summary / TL;DR {#summary}
 
-<!-- markdownlint-disable blanks-around-fences -->
+Do translate:
 
-- 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_commit` front 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:
-  ```yaml
-  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:links` and include any updates to the `.htmltest.yml`
-  config file with your PR.
+- [Front matter][] fields `title`, `linkTitle`, and `description`
+- Page content, including the text fields in Mermaid [diagrams](#images)
 
-<!-- markdownlint-enable blanks-around-fences -->
+Do **NOT**:
 
-## Translation guidance
+- Translate:
+  - **File or directory** names of resources in this repository
+  - [Links](#links), this includes [heading IDs](#headings).[^*]
+  - [Front matter][] fields other than those listed in the "Do" section above.
+    In particular, do not translate `aliases`. When in doubt, ask maintainers.
+- Create **copies of images**, unless you [localize text in the images](#images)
 
-We recommend that you follow the guidance offered in this section when
-translating pages.
+[^*]: For a possible exception, see [Links](#links).
 
-### Heading anchors
+### Heading IDs {#headings}
 
 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
+- 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.
 
-{{% alert title="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.
-
-{{% /alert %}}
-
 [Heading ID syntax]:
   https://github.com/yuin/goldmark/blob/master/README.md#headings
 
-### Links
+### Links {#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.
+Do **not** translate link references. This holds true for external links, and
+paths to website pages and section-local resources such as [images](#images).
+
+The only exception is for links to external pages (such as
+<https://en.wikipedia.org>) that have a version specific to your local. Often
+this means replacing the `en` in the URL by your locale's language code.
 
 {{% alert title="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.
+convert absolute link paths referring 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.
 
 {{% /alert %}}
 
-### Images
+### Images and diagrams {#images}
+
+Do **not** make copies of image files unless you localize text in the image
+itself[^shared-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.
+**Do** translate text in [Mermaid][] diagrams.
 
-So as a general rule, _do not_ make copies of image files in your localization
-unless you actually change the image.
+[^shared-images]:
+    Hugo is smart about the way that it renders image files that are shared
+    across site localizations. That is, Hugo will output a _single_ image file
+    and share it across locales.
+
+[Mermaid]: https://mermaid.js.org
+
+### Include files {#includes}
+
+**Do** translate page fragments found under `_includes` directories just as you
+would translate any other page content.
 
 ### Shortcodes
 
+{{% alert title="Note" %}}
+
+As of February 2025, we are in the process of migrating from shortcodes to
+[include files](#includes) as a means of supporting shared-page content.
+
+{{% /alert %}}
+
 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].
 
@@ -123,14 +122,14 @@ follows:
 ```markdown
 ---
 title: Your localized page title
-...
-
-default_lang_commit: <commit-hash-of-main-for-default-language-page>
+# ...
+default_lang_commit: <most-recent-commit-hash-of-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`.
+hash would correspond to the latest commit of `content/en/<some-path>/page.md`
+from the `main` branch.
 
 ### Tracking changes to English pages
 
@@ -285,6 +284,35 @@ if you are an approver already.
 
 {{% /alert %}}
 
+## 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:
+
+<!-- markdownlint-disable blanks-around-fences -->
+
+- 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_commit` front 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:
+  ```yaml
+  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:links` and include any updates to the `.htmltest.yml`
+  config file with your PR.
+
+<!-- markdownlint-enable blanks-around-fences -->
+
+[front matter]: https://gohugo.io/content-management/front-matter/
 [main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/
 [multilingual framework]: https://gohugo.io/content-management/multilingual/
 [PR #5386]: https://github.com/open-telemetry/opentelemetry.io/pull/5386/files

static/refcache.json

@@ -1855,6 +1855,10 @@
     "StatusCode": 200,
     "LastSeen": "2025-01-06T11:23:51.473219-05:00"
   },
+  "https://en.wikipedia.org": {
+    "StatusCode": 200,
+    "LastSeen": "2025-02-24T13:42:37.248355-05:00"
+  },
   "https://en.wikipedia.org/wiki/0.0.0.0": {
     "StatusCode": 200,
     "LastSeen": "2025-02-01T07:12:46.109395-05:00"
@@ -12939,6 +12943,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-02-01T07:12:15.787072-05:00"
   },
+  "https://gohugo.io/content-management/front-matter/": {
+    "StatusCode": 206,
+    "LastSeen": "2025-02-24T13:42:35.288155-05:00"
+  },
   "https://gohugo.io/content-management/multilingual/": {
     "StatusCode": 206,
     "LastSeen": "2025-02-01T07:09:55.106757-05:00"
@@ -13891,6 +13899,10 @@
     "StatusCode": 206,
     "LastSeen": "2025-01-24T14:37:12.587459-05:00"
   },
+  "https://mermaid.js.org": {
+    "StatusCode": 206,
+    "LastSeen": "2025-02-24T13:42:37.730493-05:00"
+  },
   "https://metricshub.com": {
     "StatusCode": 200,
     "LastSeen": "2024-10-07T14:48:00.172830893Z"