Skip to content

Commit 6badd18

Browse files
MsksgmMsksgm
committed
docs: translated contributing/localization into ja
1 parent 5472965 commit 6badd18

File tree

1 file changed

+271
-0
lines changed

1 file changed

+271
-0
lines changed

‎content/ja/docs/contributing/localization.md

+271
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
---
2+
title: サイトのローカリゼーション
3+
description: 非英語ローカリゼーションのサイトページの作成と管理
4+
linkTitle: ローカリゼーション
5+
weight: 25
6+
default_lang_commit: 5472965d7714ed898b008d41fa97561591320196
7+
cSpell:ignore: shortcodes
8+
---
9+
10+
OTel のウェブサイトは、ページのローカリゼーションをサポートするために、Hugo の [multilingual framework] をサポートしています。
11+
デフォルトの言語は英語であり、米国英語がデフォルト（暗黙の）ローカリゼーションとして設定されています。
12+
対応する言語の数は増えており、トップナビゲーションの言語ドロップダウンメニューから確認できます。
13+
14+
## 英語メンテナーガイド {#english-language-maintainer-guidance}
15+
16+
### 非英語ページのリンクチェックが失敗したとき {#when-link-checking-fails-for-non-english-pages}
17+
18+
英語は OpenTelemetry ウェブサイトのデフォルト言語です。
19+
英語のドキュメントを追加、編集、再構成した後に、非英語ページのリンクチェックが失敗する可能性があります。
20+
そのような場合は、以下を実行してください。
21+
22+
<!-- markdownlint-disable blanks-around-fences -->
23+
24+
- リンクを**修正しないでください**。それぞれの非英語ページは対応する英語のページの特定のコミット（フロントマターキーである `default_lang_commit` の Git コミットハッシュ）に関連づけられています。
25+
- 以下のフロントマター、1 つの以上のページがリンクエラーが発生している場合は最も近い祖先のファイルに非英語ページを無視するようにリンクチェッカーを設定してください。
26+
```yaml
27+
htmltest:
28+
# TODO: remove the IgnoreDirs once broken links are fixed
29+
IgnoreDirs:
30+
- path-regex/to/non-en/directory/contain/files/to/ignore
31+
- path-2-etc
32+
```
33+
- `npm run check:links` を実行して、設定ファイル `.htmltest.yml` への変更を PR に含めてください。
34+
35+
<!-- markdownlint-enable blanks-around-fences -->
36+
37+
## 翻訳ガイダンス {#translation-guidance}
38+
39+
ページの翻訳の際には、本セクションのガイドに従うことを推奨します。
40+
41+
### 見出しアンカー {#heading-anchors}
42+
43+
見出しを翻訳する際に、見出しアンカーのターゲットをローカリゼーション全体で統一するために、以下に従ってください。
44+
45+
- 見出しに明示的な ID がある場合は、それを保持する。[見出し ID の気泡][Heading ID syntax] は `{ #some-id }` のように、見出しテキストの後に記述されます。
46+
- そうでない場合は、元の英語の見出しに対して自動生成された ID に対応する明治的な ID を宣言する。
47+
48+
{{% alert title="Note" %}}
49+
50+
翻訳ページのすべての見出しに明示的な見出し ID を追加するか、リンクチェッカーで報告された既知のサイト内見出しターゲットにのみ追加するかは、ローカリゼーションの執筆者の裁量に委ねられます。
51+
前者の方法は一貫性が保たれますが、作業量が増えます。しかし、サイト外からローカリゼーションされたページのリンクをより適切にサポートでき、新しい見出しターゲットが追加された際に、過去の翻訳ページを修正する手間を減らすことができます。
52+
53+
{{% /alert %}}
54+
55+
[Heading ID syntax]: https://github.com/yuin/goldmark/blob/master/README.md#headings
56+
57+
### リンク {#links}
58+
59+
ローカルパスへ参照しているリンク（外部リンクではなく）は、そのパスのままにしてください。
60+
これは、ウェブサイトのページへのリンクや、画像などのセクション内リソースへのリンクにも当てはまります。
61+
62+
{{% alert title="Note" %}}
63+
64+
OTel ウェブサイトリポジトリには、Hugo が使用する**絶対リンクのパスをドキュメントのページにへ感する**カスタムレンダーリンクを持っています。
65+
`/docs/some-page` のようなリンクは、リンクをレンダリングする際にページの言語コードがパスの先頭に追加され、ローカライズされます。
66+
たとえば、日本語ページからレンダリングされた際に、このサンプルのパスは `/ja/docs/some-page` になります。
67+
68+
{{% /alert %}}
69+
70+
### 画像 {#images}
71+
72+
Hugo is smart in the way that it renders page images that are shared across site localizations.
73+
That is, in the generated site folder, Hugo will output a _single_ image file that is then shared across localizations.
74+
75+
So as a general rule, _do not_ make copies of image files in your localization
76+
unless you actually change the image.
77+
78+
### Shortcodes {#shortcodes}
79+
80+
Some of the base shortcodes contain English text that you might need to localize
81+
-- this is particularly true of those contained in [layouts/shortcodes/docs].
82+
83+
If you need to create a localized version of a shortcode, place it under
84+
`layouts/shortcodes/xx`, where `xx` is your localization's language code. From
85+
there, use the same relative path as the original base shortcode.
86+
87+
[layouts/shortcodes/docs]: https://github.com/open-telemetry/opentelemetry.io/tree/main/layouts/shortcodes/docs
88+
89+
## Keeping track of localized-page drift {#track-changes}
90+
91+
One of the main challenges of maintaining localized pages, is identifying when
92+
the corresponding English language pages have been updated. This section
93+
explains how we handle this.
94+
95+
### The `default_lang_commit` front-matter field {#the-default_lang_commit-front-matter-field}
96+
97+
When a localized page is written, such as `content/zh/<some-path>/page.md`, this
98+
translation is based on a specific [`main` branch commit][main] of the
99+
corresponding English language version of the page at
100+
`content/en/<some-path>/page.md`. In this repository, every localized page
101+
identifies the English page commit in the localized page's front matter as
102+
follows:
103+
104+
```markdown
105+
---
106+
title: Your localized page title
107+
...
108+
109+
default_lang_commit: <commit-hash-of-main-for-default-language-page>
110+
```
111+
112+
The front matter above would be in `content/zh/<some-path>/page.md`. The commit
113+
would correspond to the latest commit of `content/en/<some-path>/page.md` in
114+
`main`.
115+
116+
### Tracking changes to English pages {#tracking-changes-to-english-pages}
117+
118+
As updates are made to English language pages, you can keep track of the
119+
corresponding localized pages that need updating by running the following
120+
command:
121+
122+
```console
123+
$ npm run check:i18n
124+
1 1 content/en/docs/platforms/kubernetes/_index.md - content/zh/docs/platforms/kubernetes/_index.md
125+
...
126+
```
127+
128+
You can restrict the target pages to one or more localizations by providing
129+
path(s) like this:
130+
131+
```sh
132+
npm run check:i18n -- content/zh
133+
```
134+
135+
### Viewing change details {#viewing-change-details}
136+
137+
For any given localized pages that need updating, you can see the diff details
138+
of the corresponding English language pages by using the `-d` flag and providing
139+
the paths to your localized pages, or omit the paths to see all. For example:
140+
141+
```console
142+
$ npm run check:i18n -- -d content/zh/docs/platforms/kubernetes
143+
diff --git a/content/en/docs/platforms/kubernetes/_index.md b/content/en/docs/platforms/kubernetes/_index.md
144+
index 3592df5d..c7980653 100644
145+
--- a/content/en/docs/platforms/kubernetes/_index.md
146+
+++ b/content/en/docs/platforms/kubernetes/_index.md
147+
@@ -1,7 +1,7 @@
148+
---
149+
title: OpenTelemetry with Kubernetes
150+
linkTitle: Kubernetes
151+
-weight: 11
152+
+weight: 350
153+
description: Using OpenTelemetry with Kubernetes
154+
---
155+
```
156+
157+
### Adding `default_lang_commit` to new pages {#adding-default_lang_commit-to-new-pages}
158+
159+
As you create pages for your localization, remember to add `default_lang_commit`
160+
to the page front matter along with an appropriate commit hash from `main`.
161+
162+
If your page translation is based on an English page in `main` at `<hash>`, then
163+
run the following command to automatically add `default_lang_commit` to your
164+
page file's front matter using the commit `<hash>`. You can specify `HEAD` as an
165+
argument if your pages are now synced with `main` at `HEAD`. For example:
166+
167+
```sh
168+
npm run check:i18n -- -n -c 1ca30b4d content/ja
169+
npm run check:i18n -- -n -c HEAD content/zh/docs/concepts
170+
```
171+
172+
To list localization page files with missing hash keys, run:
173+
174+
```sh
175+
npm run check:i18n -- -n
176+
```
177+
178+
### Updating `default_lang_commit` for existing pages {#updating-default_lang_commit-for-existing-pages}
179+
180+
As you update your localized pages to match changes made to the corresponding
181+
English language page, ensure that you also update the `default_lang_commit`
182+
commit hash.
183+
184+
{{% alert title="Tip" %}}
185+
186+
If your localized page now corresponds to the English language version in `main`
187+
at `HEAD`, then erase the commit hash value in the front matter, and run the
188+
**add** command given in the previous section to automatically refresh the
189+
`default_lang_commit` field value.
190+
191+
{{% /alert %}}
192+
193+
If you have batch updated all of your localization pages that had drifted, you
194+
can update the commit hash of these files using the `-u` flag followed by a
195+
commit hash or 'HEAD' to use `main@HEAD`.
196+
197+
```sh
198+
npm run check:i18n -- -c <hash> <PATH-TO-YOUR-NEW-FILES>
199+
npm run check:i18n -- -c HEAD <PATH-TO-YOUR-NEW-FILES>
200+
```
201+
202+
{{% alert title="Important" %}}
203+
204+
When you use `HEAD` as a hash specifier, the script will use the hash of `main`
205+
at HEAD in your **local environment**. Make sure that you fetch and pull `main`,
206+
if you want HEAD to correspond to `main` in GitHub.
207+
208+
{{% /alert %}}
209+
210+
### Script help {#script-help}
211+
212+
For more details about the script, run `npm run check:i18n -- -h`.
213+
214+
## New localizations {#new-localizations}
215+
216+
To start a new localization for the OpenTelemetry website,
217+
[raise an issue](https://github.com/open-telemetry/opentelemetry.io/issues/) to
218+
share your interest to contribute. Tag all other individuals that are willing to
219+
write and review translations in the language you want to add. **You need at
220+
least two potential contributors**, ideally three. Include the following task
221+
list in your issue as well:
222+
223+
```markdown
224+
- [ ] Contributors for the new language: @GITHUB_HANDLE1, @GITHUB_HANDLE2, ...
225+
- [ ] Localize site homepage to YOUR_LANGUAGE_NAME
226+
- [ ] Create an issue label for `lang:LANG_ID`
227+
- [ ] Create org-level group for `LANG_ID` approvers
228+
- [ ] Update components owners for `content/LANG_ID`
229+
- [ ] Set up spell checking, if a cSpell dictionary is available
230+
```
231+
232+
Notes:
233+
234+
- For `LANG_ID`, use an official
235+
[ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1) for the language you
236+
want to add.
237+
- Look for
238+
[cSpell dictionaries](https://github.com/streetsidesoftware/cspell-dicts)
239+
available as NPM packages
240+
[@cspell/dict-LANG_ID](https://www.npmjs.com/search?q=%40cspell%2Fdict). If a
241+
dictionary isn't available for your dialect or region, choose the closest
242+
region. For an example of how to set this up, see [PR #5386].
243+
244+
After you created that issue and have the required amount of contributors,
245+
maintainers will ask you to provide a pull request with a translation of the
246+
[index page](https://github.com/open-telemetry/opentelemetry.io/blob/main/content/en/_index.md).
247+
Make sure that maintainers are allowed to edit your PR, since they will add
248+
additional changes to your PR that are required to get your localization project
249+
started.
250+
251+
With your first PR merged maintainers will take care of setting up the issue
252+
label, the org-level group and the component owners.
253+
254+
{{% alert title="Important" color="warning" %}}
255+
256+
You don't have to be an existing contributor to the OpenTelemetry project, to
257+
start a new localization. However you will not be added as a member of the
258+
[OpenTelemetry GitHub organization](https://github.com/open-telemetry/) or as a
259+
member of the approvers group for your localization. You will need to satisfy
260+
the requirements for becoming an established member and approver as outlined in
261+
the
262+
[membership guidelines](https://github.com/open-telemetry/community/blob/main/guides/contributor/membership.md).
263+
264+
When starting the localization project, maintainers will treat your reviews as
265+
if you are an approver already.
266+
267+
{{% /alert %}}
268+
269+
[main]: https://github.com/open-telemetry/opentelemetry.io/commits/main/
270+
[multilingual framework]: https://gohugo.io/content-management/multilingual/
271+
[PR #5386]: https://github.com/open-telemetry/opentelemetry.io/pull/5386/files

0 commit comments

Comments
 (0)