docs: translated contributing/localization into ja

Author: Msksgm

content/ja/docs/contributing/localization.md

@@ -0,0 +1,282 @@
+---
+title: サイトのローカリゼーション
+description: 非英語ローカリゼーションのサイトページの作成と管理
+linkTitle: ローカリゼーション
+weight: 25
+default_lang_commit: 99f0ae5760038d51f9e9eb376bb428a2caca8167
+cSpell:ignore: shortcodes
+---
+
+OTel のウェブサイトは、ページのローカリゼーションをサポートするために、Hugo の [multilingual framework] をサポートしています。
+デフォルトの言語は英語であり、米国英語がデフォルト（暗黙の）ローカリゼーションとして設定されています。
+対応する言語の数は増えており、トップナビゲーションの言語ドロップダウンメニューから確認できます。
+
+## 英語メンテナーガイド
+
+### 非英語ページのリンクチェックが失敗したとき
+
+英語は OpenTelemetry ウェブサイトのデフォルト言語です。
+英語のドキュメントを追加、編集、再構成した後に、非英語ページのリンクチェックが失敗する可能性があります。
+そのような場合は、以下を実行してください。
+
+<!-- markdownlint-disable blanks-around-fences -->
+
+- リンクを**修正しないでください**。それぞれの非英語ページは対応する英語のページの特定のコミット（フロントマターキーである `default_lang_commit` の Git コミットハッシュ）に関連づけられています。
+- 以下のフロントマター、1 つの以上のページがリンクエラーが発生している場合は最も近い祖先のファイルに非英語ページを無視するようにリンクチェッカーを設定してください。
+  ```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
+  ```
+- `npm run check:links` を実行して、設定ファイル `.htmltest.yml` への変更を PR に含めてください。
+
+<!-- markdownlint-enable blanks-around-fences -->
+
+## 翻訳ガイダンス
+
+ページの翻訳の際には、本セクションのガイドに従うことを推奨します。
+
+### 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.
+
+{{% 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
+
+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.
+
+{{% 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.
+
+{{% /alert %}}
+
+### 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.
+
+[layouts/shortcodes/docs]: https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs
+
+## 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/<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`. 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>
+```
+
+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:
+
+```console
+$ npm run check:i18n
+1       1       content/en/docs/platforms/kubernetes/_index.md - content/zh/docs/platforms/kubernetes/_index.md
+...
+```
+
+You can restrict the target pages to one or more localizations by providing
+path(s) like this:
+
+```sh
+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:
+
+```console
+$ npm run check:i18n -- -d content/zh/docs/platforms/kubernetes
+diff --git a/content/en/docs/platforms/kubernetes/_index.md b/content/en/docs/platforms/kubernetes/_index.md
+index 3592df5d..c7980653 100644
+--- a/content/en/docs/platforms/kubernetes/_index.md
++++ b/content/en/docs/platforms/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:
+
+```sh
+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
+
+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
+**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
+
+To start a new localization for the OpenTelemetry website,
+[raise an issue](https://github.com/open-telemetry/opentelemetry.io/issues/) 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:
+
+```markdown
+- [ ] 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](https://en.wikipedia.org/wiki/ISO_639-1) for the language you
+  want to add.
+- Look for
+  [cSpell dictionaries](https://github.com/streetsidesoftware/cspell-dicts)
+  available as NPM packages
+  [@cspell/dict-LANG_ID](https://www.npmjs.com/search?q=%40cspell%2Fdict). 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](https://github.com/open-telemetry/opentelemetry.io/blob/main/content/en/_index.md).
+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.
+
+{{% alert title="Important" color="warning" %}}
+
+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](https://github.com/open-telemetry/) 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](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md).
+
+When starting the localization project, maintainers will treat your reviews as
+if you are an approver already.
+
+{{% /alert %}}
+
+[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