[ja] Improvement of Localizing Kubernetes documentation for Japanese

[Okabe-Junya]

This is a Feature Request

What would you like to be added

1. Add several frequently used words
   • コンピュータ/コンピューター
   • メモリ/メモリー
   • インターフェース/インターフェイス
   • リポジトリ/リポジトリー
   • プロキシ/プロキシー
2. Add notes on whether to translate Node（ノード） or not
3. Add English notations to the header ({#section-title})
   • to avoid including Japanese in the URI

in https://github.com/kubernetes/website/blob/main/content/ja/docs/contribute/localization.md (https://kubernetes.io/ja/docs/contribute/localization)

Why is this needed

This document is read by many contributors for the first time when they contribute.

For many contributors, I think it's important to further improve this docs.

Comments

/area localization
/language ja

影響範囲が日本語ローカライゼーションに閉じており、かつ内容が日本語のコンテンツ改善の提案なので、このissueでは日本語でのやり取りを希望します。

[Okabe-Junya]

/cc @kubernetes/sig-docs-ja-reviews

↑のdescriptionにも書いた通り、以下の変更を行いたいです。特に、このドキュメントを外部から参照することも多いので、さらに良くできたらなぁと思っています。

1. 頻出単語の追加
2. ノード/Nodeの翻訳方針の追加
   • Slackでの過去のやり取り
     • FYI: https://kubernetes.slack.com/archives/CAG2M83S8/p1565142891078200
     • FYI: https://kubernetes.slack.com/archives/CAG2M83S8/p1677477746846279
     • 基本的には「ノード」で良い旨を明記したいです
3. URIに日本語を含めないようなヘッダーの追加
   • .../localization/#頻出単語 のようにリンクを共有すると、パーセントエンコーディングされることがあり、若干不便に感じていました

もしよければ、reviewer/approverの皆さんのご意見も伺いたいです（先PR作った方が良さそうであれば、そうします）

[atoato88]

/triage accepted

[atoato88]

website/scripts/ja/verify-spelling.sh にjaの内容で表記ゆれを検出するスクリプトがあります。
これを活用するのと同時に、必要であればスクリプト自体の更新も検討したいと思っています。

[Okabe-Junya]

ありがとうございます

すいません、こちらを把握していませんでした。併せて更新したいと思います

[atoato88]

ありがとうございます。
よろしくおねがいします。

[Okabe-Junya]

/assign

[t-inu]

カタカナ語の長音表記については、まず以下の原則をもっとはっきりさせたいと思いました。

• 「r」「re」「y」などで終わる単語については、原則付ける

これがあいまいで、なおかつ例外が多いのが混乱の元なのかなと。

ドキュメントの長音表記は、個人的にはmozilla.jpのガイドラインがそこそこ現状に近くて、迷うことも少ないです。
Editorial Guideline カタカナ語の表記

• 長音表記は次のとおりとする。
  • -er、-or、-ar、-cy、-ry、-gy、-xy で終わる単語はすべて長音を付加する。
    • 例: 「コンピューター」「ブラウザー」「ユーザー」「サーバー」「カレンダー」「プライバシー」「ディレクトリー」「プロキシー」
    • Microsoft のような例外はなし。
  • -ear、-eer、-re、-ty、-dy で終わる単語は長音を付加しない。
    • 例: 「ボランティア」「エンジニア」「ソフトウェア」「アクセシビリティ」「セキュリティ」「ボディ」
  • 詳細ルール

このあたりをベースにして、これには当てはめない単語(今さら変えにくい「コンテナ」など)を例外として挙げたほうが、頻出単語の表をとにかく増やすよりはやりやすくなると思いました。また、例外は極力なくしたいです。

あとは以下も見直したいです。

• スペースと括弧 () 、コロン : は半角、それ以外の記号類は全角で表記

私は記号類をほぼ全角とした経緯を知らないのですが、ASCII文字は感嘆符と疑問符だけ全角で、あとは半角としたほうが今のドキュメントに合っていますよね。
それと、括弧は半角と定義しながらも、このページ自体には全角も使われていることが気になっています。

[Okabe-Junya]

ありがとうございます、

原則をもっとはっきりさせたい
...
例外をなくしたい

というのは自分も同意で、できるだけ一定の規則に則って翻訳できると嬉しいなぁとは感じています。（一定の規則に則れるように例外を増やそうとしてしまいましたが。。）

mozillaのガイドラインを確認させて頂きましたが、確かに現行ルールとある程度一致しており、大枠はこの方針に沿う形で良いように感じました。

また例外を抽出してみると以下のようになっていました。

• バイナリ
• コンテナ
• ディレクトリ（<- 個人的には「ディレクトリー」でも良いように思います）
• レジストリ
• （リポジトリ）
  • Kubernetesのドキュメントを翻訳する には記載されていませんが、「リポジトリ」の表記が多そうですね
    • それこそGitHubの影響も大きそうですね

ということなので、t-inu さんのおっしゃる通りで、実態に近いルールに則り、（k8sの分野で特に重要な少数の単語に対して）例外を設ける形の方が良いかもしれませんね

（後は先にissueに切り出してしまって申し訳ないんですが "interface" は「インターフェース」で良さそうですかね？？）ref. #45038

[Okabe-Junya]

• スペースと括弧 () 、コロン : は半角、それ以外の記号類は全角で表記

のルールについても考えてみたのですが、

ASCII文字は感嘆符と疑問符だけ全角で、あとは半角

で良いように感じました。（現行ルールだと、;, /, <>, = あたりの判断が難しいかもしれないですね）

[nasa9084]

ありがとうございます！

mozilla.jpのガイドライン + 例外

良さそうに思えます

記号類をほぼ全角とした経緯

これは特に深く議論した記憶も無いので、ふわっと決めた気がします・・・なので

ASCII文字は感嘆符と疑問符だけ全角で、あとは半角

で良いと思います

括弧は半角と定義しながらも、このページ自体には全角も使われている

これは本当に申し訳ないのですがただのミスだと思います・・・立ち上げ当時はKubernetesの公式なプロジェクトではなかったので外部サービスにこのガイドを置いていたので、そのあたりレビューをせずに書いて、それをそのままgithubに持ってきた、という経緯でした。

"interface" は「インターフェース」

ggった感じはインターフェースの方が多そうなのでインターフェースがvalidで行きましょう

[Okabe-Junya]

みなさんありがとうございます :)

では、以下のようにルールを更新する形でよろしいでしょうか？

---

新規ルール

• 大枠は mozilla.jpのガイドライン に従う
• 少数の専門単語をこの例外にする
  • 例外にする単語
    • コンテナ
    • バイナリ
  • 例外にするか別途検討する単語
    • ディレクトリ（ルール上は「ディレクトリー」）
    • リポジトリ（ルール上は「リポジトリー」）
      • 現行ルールでは特筆されていませんが、GitHubでは「リポジトリ」という表記なので、「リポジトリー」という表記は反直感的な気がします
        • FYI: https://docs.github.com/ja/repositories
    • レジストリ（ルール上は「レジストリー」）
• 記号類は感嘆符 ！ と疑問符 ？ だけ全角、その他は半角

---

あとはこのルールに沿うように、https://kubernetes.io/ja/docs/contribute/localization と scripts/ja/verify-spelling.sh を更新できればと思います。

@nasa9084 @atoato88 @t-inu

この方針で良いでしょうか？？また、「ディレクトリ」「リポジトリ」「レジストリ」は例外としますか？？

[Okabe-Junya]

「ディレクトリ」「リポジトリ」「レジストリ」は例外としますか？？

個人的には「リポジトリ」だけは例外とし、「ディレクトリ」「レジストリ」はルールに従うように変更（「ディレクトリー」「レジストリー」）するのが良いと思いました

[Okabe-Junya]

（少し別の内容になりますが、）Contribute/Review している際に、例えば以下の内容は暗黙の了解的になっているなぁと感じているので、合わせて更新したいと考えています。（忘れないうちに書き残しておきますね。。）

• Metadataの取り扱い
  • reviewerは削除する。title, descriptionは翻訳する。type, weightはママ
• 既に日本語翻訳が存在する文章へのinternalリンクは/ja/page/to/ref のように/jaを先頭に追加する
• 日本語訳は一文を一行にする（文中で改行しない）

[atoato88]

@Okabe-Junya
反応が遅れて申し訳ありません。
ここまでで提案いただいている内容で私は違和感ありません。

個人的にはこのあたりは決めの問題だと思っていて、それがさらに明確になってきているという意味でとても助かります。

[atoato88]

あと、これも別トピックになりますが、以下２つをだいぶ前から実装できないか考えていました。

• scripts/ja/verify-spelling.sh をPR作成時やPRのアップデート時に自動実行してチェックしたい。
• PRが作られるとNetlifyでデプロプレビューを見ることができますが、そのNetlifyのデプロイプレビュー上での更新されたページへのURLを自動でPRに追加コメントしたい。
  • 私が気がついたやつは手動でそのようなリンクをコメントしているのですが、自動化できるとレビューも捗ると思っています。

ここではトピックの共有だけで、掘り下げのディスカッションをここでするつもりはありませんが、関連してそうだと思ったので共有させてもらいました。

[Okabe-Junya]

ありがとうございます、

では、一旦このまま進めたいと思います。（何かあれば、別途PRレビューの方でお願いします）関連トピックの方もありがとうございます。把握している情報を書き留めておきます

===

scripts/ja/verify-spelling.sh をPR作成時やPRのアップデート時に自動実行してチェックしたい。

おっしゃる通りで、自分もかなり感じています。 #43335 でそのような話は出ているんですよね。。あまり動いていなさそうなので、もしかしたら、先に scripts/ja/verify-spelling.sh を k/test-infra に導入しにいくかもしれないです（メンテナに確認します）

PRが作られるとNetlifyでデプロプレビューを見ることができますが、そのNetlifyのデプロイプレビュー上での更新されたページへのURLを自動でPRに追加コメントしたい。

これもおっしゃる通りですね。（あまりよくわかっていないのですが）フルパスで表示されることもあるので、netlify側で頑張れば解決できるかもしれないですね。。

• パスが表示される例: [ja] Localize Application Programming Interface (API) for Japanese cncf/glossary#2691 (comment)

[t-inu]

新しいルールをまとめていただいて助かります。

遅くなりましたが、「ディレクトリ」「リポジトリ」「レジストリ」についてコメントします。
リポジトリは、コードやファイルの保存場所という意味で、GitHub固有の用語というわけでもないと思っています。
同様に、レジストリは情報を登録しておく機関や場所という意味で、WindowsだけでなくDockerやDNSなどでも使われますね。
なので、「GitHubではリポジトリの表記なので例外にしましょうか」は、「Windowsではレジストリの表記なので例外にしましょうか」と同じことに思えました。
「この製品やドキュメントではこの表記だった」というのを部分的に採用していくと、ルールがぶれていきそうです。
特にこの3つは意味も語呂も似ていて、この中の1つだけ例外にすると、毎回どれがどちらだったか気にする必要があり、煩わしくなるのではという懸念があります。

また、これとは別の話ですが、特定のアプリケーションやサービスなどの名称や、操作対象の項目名といったものを記載する場合は、その表記に合わせたほうがよいでしょうね。
例えば、Windowsでの操作説明をする必要があるとして、「レジストリ エディター」は、その製品固有のツール名であり、表記されているままにするのがよいと思っています。

[t-inu]

この機会に、マイクロソフトの長音表記の詳細を調べてみました。
複雑で例外も多いので、Mozilla Japanではそのまま採用はしなかったのではと思いました。
Localization Style Guides

• -er -or -arは伸ばす
• 4文字以下なら伸ばす(「ー」自体もカウントし、「ッ,ャ,ュ,ョ,ァ,ィ,ゥ」はカウントしない)
  • queue 2文字(キ,ー) → キュー
  • menu 3文字(メ,ニ,ー) → メニュー
  • memory 4文字(メ,モ,リ,ー) → メモリ
  • procedure 6文字(プ,ロ,シ,ー,ジ,ー) → プロシージャ
• 英単語が接頭辞や接尾辞で構成されている場合は、分けて考える
  • preview (pre + view) 2文字(ビ,ー) → プレビュー
  • subtree (sub + tree) 2文字(ツ,リ,ー) → サブツリー
  • interface (inter + face) interは-erなので伸ばす → インターフェイス
    • Mozilla(詳細ルール)もマイクロソフトも「インターフェイス」の表記なんですね…。
      一方、GoogleやIBMなどは「インターフェース」なので、どちらが主流とも判断しづらいです。
• 慣例に従って例外とする用語が120語ある

[Okabe-Junya]

コメントありがとうございます

「この製品やドキュメントではこの表記だった」というのを部分的に採用していくと、ルールがぶれていきそうです。

確かにそうですね。「リポジトリ」だけ例外にしたかった経緯としては、k/website（このリポジトリ）がGitHub上にホスティングされており、GitHubにおける主要な概念である「リポジトリ」が公式と異なる表記になることを避けたかったというものがありました。

少しマクロな視点で考えてみて、そもそも末尾 "ry" は長音を付与しないでも良いのではとも思いました。つまり、特定の単語ではなく、ルールとしてそのように制定してしまうという方針です。主観ですが、以下に挙げる単語は長音を表記しない方が一般的な印象です。特に、権威生のあるサイトでも長音表記しないことが多いように見受けられます（MySQL, GitHub, OpenTelemetory は機械翻訳ですが。。）

• バイナリ
• レジストリ
  • Docker-docs-ja / Docker レジストリ の理解 では、「レジストリ」表記です
• ライブラリ
• クエリ
  • MySQLリファレンスでは「クエリー」、Postgresは「クエリ」表記です
    • mysql: https://dev.mysql.com/doc/refman/8.0/ja/entering-queries.html
    • postgres: https://www.postgresql.jp/document/15/html/parallel-query.html
• リポジトリ
  • GitHubでは「リポジトリ」表記です（https://docs.github.com/ja/repositories ）
• メモリ
• テレメトリ
  • AppDynamics / OpenTelemetry とは では「テレメトリ」表記です

逆に、以下のような単語は、長音を付与することが一般的な印象です。

• サマリー
• ヒストリー
• セオリー
• バッテリー
• ディスカバリー

総括として、特に専門性の高い用語では "ry" は長音は付与しない印象です。ルール自体を変更しても良いのかなと思いました。とはいえ、現行ルールと干渉するという最大の障壁があるのですが。。

[Okabe-Junya]

この機会に、マイクロソフトの長音表記の詳細を調べてみました。
複雑で例外も多いので、Mozilla Japanではそのまま採用はしなかったのではと思いました。

自分も確かに少し分かりづらい印象を受けました。むしろ、Mozilla Japanが非常に簡潔にまとまっている & 現行ルールに近いので、やはり大枠としては適切な気がします

[t-inu]

専門性の高い用語ほど長音記号をつけない印象があるのは、過去にJISが3音以上の場合には付与しないルールにしていたからでしょうね。
2008年にマイクロソフトが現在の表記ルールに変更したことや、JISのルールも内閣告示の外来語の表記に沿うことになって、「コンピューター」「サーバー」のような表記がIT業界でも浸透してきました。

一方で、「メモリ」「ディレクトリ」といった表記を今でもよく見かけるのは、マイクロソフトもJISも、"-ry" を原則伸ばすルールにはしなかったことの影響が大きい気がしています。
ここがずっと迷っているところなんですが、現在の多数派に合わせるなら長音を付与しないほうが違和感が少なくて、それでもいいかなと思い始めています。

そうすると、原則の説明として、Mozilla Japanのルールをそのまま引用して載せると混乱しそうですよね。例まで書いてあるのでなおさらです。
あくまで参考にしたということでリンクはするとして、Kubernetesのドキュメントとして採用するルールは改めて記載したほうがいいように思いました。
また、-xyはproxyくらいしか本ドキュメントでは使うことがなさそうなので、原則には含めずに、「その他の表記」にプロキシを入れておく案はどうでしょうか。

ルールはこんな感じで、例はそれぞれに1つ用意して、せっかくなのでよく使いそうな単語にしてみました。

• -er、-or、-ar、-cy、-gyで終わる単語は長音を付加する。
  • 例: 「クラスター」「セレクター」「サイドカー」「ポリシー」「トポロジー」
• -ear、-eer、-re、-ty、-dy、-ryで終わる単語は長音を付加しない。
  • 例: 「クリア」「エンジニア」「アーキテクチャ」「セキュリティ」「スタディ」「ディレクトリ」

例外: コンテナ
その他の表記: プロキシ、アドオン、～

[Okabe-Junya]

新規ルール案を例を加えて提示していただきありがとうございます。

一方で、「メモリ」「ディレクトリ」といった表記を今でもよく見かけるのは、マイクロソフトもJISも、"-ry" を原則伸ばすルールにはしなかったことの影響が大きい気がしています。
ここがずっと迷っているところなんですが、現在の多数派に合わせるなら長音を付与しないほうが違和感が少なくて、それでもいいかなと思い始めています。

自分も完全に同意で、"ry" の表記が多くの文章と異なるルールなので変更したいと考えています。ご提示いただいたルールはぜひそのまま採用させて頂きたいなと思いました。

またプロキシを「その他の表記」として扱うというのも納得なのですが、逆に何をその他の表記で載せるべきでしょうか。。？？現行の https://kubernetes.io/ja/docs/contribute/localization/#頻出単語 のうち 長音、固有名詞以外の理由で掲載されているもの を抽出してみると以下の通りです。（あとはプロキシ、インターフェースあたりも追加する感じでしょうか。。）

• Addon/Add-on: アドオン
• orchestrate(動詞): オーケストレーションする
• For more information: さらなる情報
• prefix: プレフィックス
• Quota: クォータ
• a set of ~: ～の集合
• stacked: 積層

この中で「表記」として統一したい単語は、

• プロキシ
• クォータ
• 積層
• インターフェース

くらいで、後はケースバイケースで訳せば良いように感じます。（例えばアドオンは日本語では表記揺れするものではないし、prefixも適宜「接頭辞」と訳せば良いと思いました。"orchestrate" も本来の意味で「編曲する」のように訳されると多くの場合は困りますが、それをk8sの文脈でわざわざ明示しなくても良いように感じます）

改めてまとめると、t-inuさんが提示していただいたルールを採用 + 最小限の例外、表記を記載しておく。表記は↑にあげた4単語のみを記載する。という構成でどうでしょうか？

[t-inu]

現行の頻出単語は、私が初めて見たときから存在していて、どういう経緯で載せることになったのか知らないものばかりです。
「アドオン」は、ママ表記でなくカタカナにしましょうということなのか、あるいは「付加機能」のような訳し方をしなくていいということなのか…。
「さらなる情報(一時的)」の、一時的の意味もちょっとわかりません。

今回、ルールを明確にすることで表記に迷うことがなくなる単語は、削除して構わないと思います。
あとは、私では判断しにくいところもあるのですが、一旦それくらいすっきりさせて、また必要性を感じたら追加していく運用でもいいのかなと。

[Okabe-Junya]

色々とご提案いただき、ありがとうございました。大枠に関しては方針が定まったと思うので、改めてPRの方を更新させて頂きます。

細かい表現や最終的な確認はそこで行えればと思います。（PRの方にも記載しましたが、at least oneではなく、皆さんに確認していただけると嬉しいです）

[nasa9084]

しばらくおってなくてすみません。
頻出単語は当時GitHub上ではなくて外部のwiki的な奴(Kibelaだった)に置いていたということで、もっと頻繁に更新する想定だったんですよね・・・そしてそれを後から公式のwebsiteに移したという経緯があります

「さらなる情報(一時的)」の、一時的の意味もちょっとわかりません。

とかは多分(記憶が曖昧なのですが)当時、適切な訳として良いかどうかは分からないけど、ちょっと訳に迷ったか何かして、とりあえずこういう訳にすることにしました、ということで(一時的)と書いたんじゃないかという気がします
アドオンとかも、よく出てくるからということで気軽に書いただけだったかと思います・・・

今回、ルールを明確にすることで表記に迷うことがなくなる単語は、削除して構わないと思います。

このへんとかは全然それで問題ないというか、むしろそれでわかりやすくなるのであれば積極的におねがいします、という感じです

[Okabe-Junya]

みなさま議論に参加して頂きありがとうございました！色々とお願いしてばかりでしたが、無事にマージできました 🎉

/close

[k8s-ci-robot]

@Okabe-Junya: Closing this issue.

In response to this:

みなさま議論に参加して頂きありがとうございました！色々とお願いしてばかりでしたが、無事にマージできました 🎉

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.