[i18n] Introduce notranslate convention and guidance (#6595)

Author: chalin

content/en/docs/contributing/localization.md

@@ -25,7 +25,7 @@ guidance offered in this section.
 - **Translate**:
   - Page content, including:
     - Mermaid [diagram](#images) text fields
-    - Code comments from code excerpts
+    - Code comments from code excerpts (optional)
   - [Front matter][] field values for `title`, `linkTitle`, and `description`
   - **All** page content and front matter unless indicated otherwise
 - **Preserve** the _content_, _meaning_, and _style_ of the original text
@@ -45,6 +45,9 @@ guidance offered in this section.
 - **Translate**:
   - **File or directory** names of resources in this repository
   - [Links](#links), this includes [heading IDs](#headings).[^*]
+  - Inline code-spans like these: `inline code example`
+  - Markdown elements marked as `notranslate` (usually as a CSS class), in
+    particular for [headings](#headings)
   - [Front matter][] fields other than those listed in [Do](#do). In particular,
     do not translate `aliases`. When in doubt, ask maintainers.
   - Code

content/en/docs/contributing/pr-checks.md

@@ -2,36 +2,34 @@
 title: Pull request checks
 description: Learn how to make your pull request successfully pass all checks
 weight: 40
-cSpell:ignore: REFCACHE
 ---
 
 When you raise a
 [pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)
 (PR) with the
 [opentelemetry.io repository](https://github.com/open-telemetry/opentelemetry.io)
-a set of checks are executed. The PR checks verify that...
+a set of checks are executed. The PR checks verify that:
 
-- … you have signed the [CLA](#easy-cla).
-- …your commit can be deployed through [Netlify](#netlify-deployment)
-  successfully.
-- … your changes are compliant with our [style guide](#style-checks).
+- You have signed the [CLA](#easy-cla)
+- Your PR successfully [deploys through Netlify](#netlify-deployment)
+- Your changes are compliant with our [style guide](#style-checks)
 
 {{% alert title="Note" color="primary" %}}
 
 If any of the PR checks fails, try to
-[fix content issues automatically](../pull-requests/#fix-issues) first by
-running `npm run fix:all` on your machine.
+[fix content issues](../pull-requests/#fix-issues) first by running
+`npm run fix:all` locally.
 
-Additionally, you can comment `/fix:all` on your Pull Request. This will make
-the OpenTelemetry Bot run those commands on your behalf and update the PR. Make
+You can also add the comment `/fix:all` to your PR. This will trigger the
+OpenTelemetry Bot to run that command on your behalf and update the PR. Make
 sure that you pull those changes locally.
 
 Only if your issues persist, read below what the different checks do and how you
 can recover from a failed state.
 
 {{% /alert %}}
 
-## Easy CLA
+## `Easy CLA` {.notranslate lang=en}
 
 This check fails if you haven't [signed the CLA](../prerequisites/#cla).
 
@@ -49,7 +47,7 @@ find any issues.
 The following list describes current checks and what you can do to fix related
 errors:
 
-### TEXT linter
+### `TEXT linter` {.notranslate lang=en}
 
 This check verifies that
 [OpenTelemetry-specific terms and words are used consistently across the site](../style-guide/#opentelemetryio-word-list).
@@ -59,51 +57,51 @@ If any issues are found, annotations are added to your files in the
 alternative, you can run `npm run check:text -- --fix` locally to fix most
 issues. Run `npm run check:text` again and manually fix the remaining issues.
 
-### MARKDOWN linter
+### `MARKDOWN linter` {.notranslate lang=en}
 
 This check verifies that
 [standards and consistency for Markdown files are enforced](../style-guide/#markdown-standards).
 
-If any issues are found, run `npm run:format` to fix most issues. For more
+If any issues are found, run `npm run fix:format` to fix most issues. For more
 complex issues, run `npm run check:markdown` and apply the suggested changes.
 
-### SPELLING check
+### `SPELLING check` {.notranslate lang=en}
 
 This check verifies that
 [all words are spelled correctly](../style-guide/#spell-checking).
 
-### CSPELL:IGNORE check
+### `CSPELL` check {.notranslate lang=en}
 
 This check will verify that all words in your cSpell ignore list are normalized.
 
 If this check fails, run `npm run fix:dict` locally and push the changes in a
 new commit.
 
-### FILENAME check
+### `FILENAME check` {.notranslate lang=en}
 
 This check verifies that all
 [files are formatted by prettier](../style-guide/#file-format).
 
-If this check fails, run `npm fix:format` locally and push the changes in a new
-commit.
+If this check fails, run `npm run fix:format` locally and push the changes in a
+new commit.
 
-### FILE FORMAT
+### `FILE FORMAT` {.notranslate lang=en}
 
 This check verifies that all
 [file names are in kebab-case](../style-guide/#file-names).
 
-If this check fails, run `npm fix:filenames` locally and push the changes in a
-new commit.
+If this check fails, run `npm run fix:filenames` locally and push the changes in
+a new commit.
 
-### BUILD and CHECK LINKS / REFCACHE updates?
+### `BUILD and CHECK LINKS` {.notranslate lang=en}
 
-This check verifies that all links that your commits are introducing are
-functional.
+This check builds the website and verifies that all links are valid.
 
-Run `npm run check:links` to check them locally. This also updates the reference
-cache, or `REFCACHE`. Push any changes to the `REFCACHE` in a new commit.
+To check links locally, run `npm run check:links`. This command also updates the
+reference cache. Push any changes to the refcache in a new commit.
 
-### WARNINGS in build log?
+### `WARNINGS in build log?` {.notranslate lang=en}
 
-If this check fails, review the build log for any other potential issues. Ask
-maintainers for help, if you are unsure how to recover.
+If this check fails, review the `BUILD and CHECK LINKS` log, under the
+`npm run log:check:links` step, for any other potential issues. Ask maintainers
+for help, if you are unsure how to recover.