From f212c2a88e9dbc991be6bdf2b4ec867578b55148 Mon Sep 17 00:00:00 2001 From: Msksgm Date: Sun, 9 Feb 2025 14:35:15 +0900 Subject: [PATCH 1/6] docs: translated contributing/style-guide into ja --- content/ja/docs/contributing/style-guide.md | 105 ++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 content/ja/docs/contributing/style-guide.md diff --git a/content/ja/docs/contributing/style-guide.md b/content/ja/docs/contributing/style-guide.md new file mode 100644 index 000000000000..6d7777f1715f --- /dev/null +++ b/content/ja/docs/contributing/style-guide.md @@ -0,0 +1,105 @@ +--- +title: ドキュメントスタイルガイド +description: OpenTelemetry のドキュメントを書く際の用語とスタイル。 +linkTitle: スタイルガイド +weight: 20 +default_lang_commit: 35fde3d29a49ddea001ef99ffcbbe702a003e70f +cSpell:ignore: open-telemetry postgre style-guide textlintrc +--- + +公式のスタイルガイドはまだありませんが、現在の OpenTelemetry ドキュメントのスタイルは以下のスタイルガイドに触発されています。 + +- [Google Developer Documentation Style Guide](https://developers.google.com/style) +- [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide/) + +後述するセクションは、OpenTelemetry プロジェクト特有のガイドを含んでいます。 + +{{% alert title="Note" color="primary" %}} + +スタイガイドの多くの要件されることは、自動化で強制されています。 +[pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)(PR) を提出する前に、ローカルで `npm run fix:all` を実行して、変更をコミットしてください。 + +エラーまたは [failed PR checks](../pr-checks) に遭遇した場合、スタイガイドを読んで特定の一般的な問題を修正するのにできることを学んでください。 + +{{% /alert %}} + +## OpenTelemetry.io ワードリスト {#opentelemetryio-word-list} + +OpenTelemetry 特有の用語や単語の一覧であり、サイト全体で一貫して利用されるべきもの。 + +- [OpenTelemetry](/docs/concepts/glossary/#opentelemetry) and + [OTel](/docs/concepts/glossary/#otel) +- [Collector](/docs/concepts/glossary/#collector) +- [OTEP](/docs/concepts/glossary/#otep) +- [OpAMP](/docs/concepts/glossary/#opamp) + +OpenTelemetry の用語と定義の完璧なリストには、[Glossary](/docs/concepts/glossary/) を参照してください。 + +ほかの CNCF プロジェクトやサードパーティツールなどの固有名詞は、適切に表記し、元の大文字・小文字の区別を正しく維持してください。 +例えば、"postgre" のかわりに "PostgreSQL" と表記してください。 +全てのリストは、[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) を確認してください。 + +{{% alert title="Tip" %}} + +すべての用語と単語が適切に記載されていることを検証するために、`npm run check:text` を実行してください。 + +適切に記載されていない用語と単語を修正するために `npm run check:text -- --fix` を実行してください。 + +{{% /alert %}} + +## マークダウン規約 {#markdown-standards} + +マークダウンファイルに規約と一貫性を確保するために、[markdownlint] によって定められたルールに従う必要があります。 +すべてのルールの一覧は、[.markdownlint.json] ファイルを確認してください。 + +以下を実行してください。 + +- `npm run check:markdown` はすべてのファイルが規約に従っていることを保証します。 +- `npm run fix:markdown` はマークダウンに関連するフォーマットの問題を修正します。 + +同様に、Markdown [file format](#file-format) を適用し、ファイルの末尾スペースを削除します。 +これは 2 つ以上のスペースを仕様する [line break syntax] を排除します。 +かわりに `
` を使うか、再フォーマットしてください。 + +## スペルチェック {#spell-checking} + +すべてのテキストが適切に表記されているあ確認するために、[CSpell](https://github.com/streetsidesoftware/cspell) を使用します。 +OpenTelemetry ウェブサイト固有の単語一覧は、[`.cspell.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.cspell.yml) ファイルを確認してください。 + +すべての単語が正しいことを確認するために、`npm run check:spelling` を実行してください。 +`cspell` が `Unknown word` エラーを示した場合、単語を正しく記述したか確認してください。 +正しく場合、ファイルの先頭にある `cSpell:ignore` セクションに単語を追加してください。 +そのようなセクションがない場合は、Markdown ファイルの Front Matter に追加できます。 + +```markdown +--- +title: PageTitle +cSpell:ignore: +--- +``` + +ほかのファイルの場合は、そのファイルの状況に適したコメント行に `cSpell:ignore ` を追加してください。 +たとえば、[レジストリ](/ecosystem/registry/) エントリー YAML ファイルでは、次のように記述します。 + +```yaml +# cSpell:ignore +title: registryEntryTitle +``` + +ウェブサイトのツールは、重複した単語の排除、グローバル単語リストにある単語を削除、単語をソートすることで、ページ固有の辞書（つまり、`cSpell:ignore` 単語リスト）を標準化します。 +ページ固有の辞書を標準化するには、`npm run fix:dict` を実行してください。 + +## ファイルのフォーマット {#file-format} + +[Prettier] を利用することでファイルフォーマットを強制します。 +`npm run fix:format` を実行して、フォーマットを適用してください。 + +## ファイル名 {#file-names} + +すべてのファイル名は、[kebab case](https://en.wikipedia.org/wiki/Letter_case#Kebab_case) である必要があります。 +`npm run fix:filenames` を実行して、ファイルを自動的にリネームしてください。 + +[.markdownlint.json]: https://github.com/open-telemetry/opentelemetry.io/blob/main/.markdownlint.json +[line break syntax]: https://www.markdownguide.org/basic-syntax/#line-breaks +[markdownlint]: https://github.com/DavidAnson/markdownlint +[Prettier]: https://prettier.io From f736c8183fa76cb82807accfc8ca2e171ca18e58 Mon Sep 17 00:00:00 2001 From: Msksgm Date: Mon, 10 Feb 2025 16:34:03 +0900 Subject: [PATCH 2/6] =?UTF-8?q?fix:=20typo=20`=E3=82=B9=E3=82=BF=E3=82=A4?= =?UTF-8?q?=E3=82=AC=E3=82=A4=E3=83=89`=20to=20`=E3=82=B9=E3=82=BF?= =?UTF-8?q?=E3=82=A4=E3=83=AB=E3=82=AC=E3=82=A4=E3=83=89`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/ja/docs/contributing/style-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ja/docs/contributing/style-guide.md b/content/ja/docs/contributing/style-guide.md index 6d7777f1715f..641cce14414a 100644 --- a/content/ja/docs/contributing/style-guide.md +++ b/content/ja/docs/contributing/style-guide.md @@ -16,10 +16,10 @@ cSpell:ignore: open-telemetry postgre style-guide textlintrc {{% alert title="Note" color="primary" %}} -スタイガイドの多くの要件されることは、自動化で強制されています。 +スタイルガイドの多くの要件されることは、自動化で強制されています。 [pull request](https://docs.github.com/en/get-started/learning-about-github/github-glossary#pull-request)(PR) を提出する前に、ローカルで `npm run fix:all` を実行して、変更をコミットしてください。 -エラーまたは [failed PR checks](../pr-checks) に遭遇した場合、スタイガイドを読んで特定の一般的な問題を修正するのにできることを学んでください。 +エラーまたは [failed PR checks](../pr-checks) に遭遇した場合、スタイルガイドを読んで特定の一般的な問題を修正するのにできることを学んでください。 {{% /alert %}} From 62a5841ab6b46ec11515405e4b58a08ad9f6cd51 Mon Sep 17 00:00:00 2001 From: Msksgm Date: Mon, 10 Feb 2025 16:34:38 +0900 Subject: [PATCH 3/6] fix: missing translated word of `and` --- content/ja/docs/contributing/style-guide.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/ja/docs/contributing/style-guide.md b/content/ja/docs/contributing/style-guide.md index 641cce14414a..417755f886ed 100644 --- a/content/ja/docs/contributing/style-guide.md +++ b/content/ja/docs/contributing/style-guide.md @@ -27,8 +27,7 @@ cSpell:ignore: open-telemetry postgre style-guide textlintrc OpenTelemetry 特有の用語や単語の一覧であり、サイト全体で一貫して利用されるべきもの。 -- [OpenTelemetry](/docs/concepts/glossary/#opentelemetry) and - [OTel](/docs/concepts/glossary/#otel) +- [OpenTelemetry](/docs/concepts/glossary/#opentelemetry) と [OTel](/docs/concepts/glossary/#otel) - [Collector](/docs/concepts/glossary/#collector) - [OTEP](/docs/concepts/glossary/#otep) - [OpAMP](/docs/concepts/glossary/#opamp) From b074e7704b2ec360291d8da13ea1f52ac10f5961 Mon Sep 17 00:00:00 2001 From: Msksgm Date: Mon, 10 Feb 2025 16:35:41 +0900 Subject: [PATCH 4/6] =?UTF-8?q?fix:=20`=E4=BE=8B=E3=81=88=E3=81=B0`=20to?= =?UTF-8?q?=20`=E3=81=9F=E3=81=A8=E3=81=88=E3=81=B0`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/ja/docs/contributing/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/contributing/style-guide.md b/content/ja/docs/contributing/style-guide.md index 417755f886ed..b6c0203fa056 100644 --- a/content/ja/docs/contributing/style-guide.md +++ b/content/ja/docs/contributing/style-guide.md @@ -35,7 +35,7 @@ OpenTelemetry 特有の用語や単語の一覧であり、サイト全体で一 OpenTelemetry の用語と定義の完璧なリストには、[Glossary](/docs/concepts/glossary/) を参照してください。 ほかの CNCF プロジェクトやサードパーティツールなどの固有名詞は、適切に表記し、元の大文字・小文字の区別を正しく維持してください。 -例えば、"postgre" のかわりに "PostgreSQL" と表記してください。 +たとえば、"postgre" のかわりに "PostgreSQL" と表記してください。 全てのリストは、[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) を確認してください。 {{% alert title="Tip" %}} From 36997a0c409f66099acc8177867320b1d1d18ab2 Mon Sep 17 00:00:00 2001 From: Msksgm Date: Mon, 10 Feb 2025 16:35:57 +0900 Subject: [PATCH 5/6] =?UTF-8?q?fix:=20`=E5=85=A8=E3=81=A6`=20to=20`?= =?UTF-8?q?=E3=81=99=E3=81=B9=E3=81=A6`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/ja/docs/contributing/style-guide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/ja/docs/contributing/style-guide.md b/content/ja/docs/contributing/style-guide.md index b6c0203fa056..60d224997a16 100644 --- a/content/ja/docs/contributing/style-guide.md +++ b/content/ja/docs/contributing/style-guide.md @@ -36,7 +36,7 @@ OpenTelemetry の用語と定義の完璧なリストには、[Glossary](/docs/c ほかの CNCF プロジェクトやサードパーティツールなどの固有名詞は、適切に表記し、元の大文字・小文字の区別を正しく維持してください。 たとえば、"postgre" のかわりに "PostgreSQL" と表記してください。 -全てのリストは、[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) を確認してください。 +すべてのリストは、[`.textlintrc.yml`](https://github.com/open-telemetry/opentelemetry.io/blob/main/.textlintrc.yml) を確認してください。 {{% alert title="Tip" %}} From f5535232ac7c214149f8066681b0682f561c18b3 Mon Sep 17 00:00:00 2001 From: Msksgm Date: Mon, 10 Feb 2025 16:39:33 +0900 Subject: [PATCH 6/6] fix: link titles which have been already translated into ja --- content/ja/docs/contributing/style-guide.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/ja/docs/contributing/style-guide.md b/content/ja/docs/contributing/style-guide.md index 60d224997a16..6fd8096b6b4a 100644 --- a/content/ja/docs/contributing/style-guide.md +++ b/content/ja/docs/contributing/style-guide.md @@ -28,11 +28,11 @@ cSpell:ignore: open-telemetry postgre style-guide textlintrc OpenTelemetry 特有の用語や単語の一覧であり、サイト全体で一貫して利用されるべきもの。 - [OpenTelemetry](/docs/concepts/glossary/#opentelemetry) と [OTel](/docs/concepts/glossary/#otel) -- [Collector](/docs/concepts/glossary/#collector) +- [コレクター](/docs/concepts/glossary/#collector) - [OTEP](/docs/concepts/glossary/#otep) - [OpAMP](/docs/concepts/glossary/#opamp) -OpenTelemetry の用語と定義の完璧なリストには、[Glossary](/docs/concepts/glossary/) を参照してください。 +OpenTelemetry の用語と定義の完璧なリストには、[用語集](/docs/concepts/glossary/) を参照してください。 ほかの CNCF プロジェクトやサードパーティツールなどの固有名詞は、適切に表記し、元の大文字・小文字の区別を正しく維持してください。 たとえば、"postgre" のかわりに "PostgreSQL" と表記してください。