[ja] Clarify the localization process for kubernetes-specific terminologies (especially for boundary cases)

[youmeim]

This is a Feature Request

What would you like to be added

Modify the localization guide for kubernetes terminology .

Why is this needed

Our translation guideline is well-working and also enough simple and well-covered for our translation workflow itself and the localization guide for kubernetes terminology successfully works for separating alphabetical results (or カタカナ語) and other words translated into Japanese.

However there are uncovered cases for several term categories, especially for newer functionalities or non-API resource terms, such as:

• Validating Admission Controller (or Validating Admission Webhook)
• Guaranteed QoS
• Pod Security Standard

These terms (or other future terms on k8s) are not perfectly covered by our translation guideline, because these terms are not composed of purely k8s-specific concepts and also they are not resources.

Additionally, these terms are originated and derived from domain specific knowledge in neighbor technologies of k8s (such as network engineering, service management, access control or auditing, etc.), some contributors may assume that there is a Japanese counterpart for a word composing the term. Such decisions by a contributor (and reviewers) seem to be performed per-contribution, and the ambiguity of the localization workflow for several boundary terms possibly results different translations for the same term by different contributors (on different pages spread on the website). Audiences of the localized website can be confused by the variety of a translated k8s term.

In present (and in past), boundary terms categorized above were translated and reviewed per-PR, translated AS-IS, and seems not to be referred from the new contribution for other pages in every time.

We, contributors, have various backgrounds, different knowledge and different levels of comprehension and experience on k8s and its related technologies. So we should clarify or redefine the translation workflow even for these boundary cases, to empower localization contributors and to reduce the workload of reviewers.

---

Comments

Proposal

Here, I have two proposal to improve the localization guide for kubernetes terminology, to reduce the ambiguity of localization process on k8s-specific terms.

Proposal 1 Add a flow chart for the eye-catch of the section

Provide a flow chart to support contributors and reviewers for boundary cases, to detect whether a term should be translated into Japanese or not.
For example:

This kind of flow chart can be used as the initial check or the final check for a contribution, and it will improve the performance of the contributor (possibly a newcomer or a reviewer) to reduce the time consumption to choose or find certain solution for boundary cases of the translation of k8s terminology.

Proposal 2 Add notes for new contributors (and also for reviewers and maintainers) to describe that:

• The list of API resources, the glossary page and the localization guide should be checked to reduce boundary cases for your translation.
• Any boundary cases are processed within the table その他の表記.
• If you make a consensus for the translation of the boundary case with reviewers, you (contributor) should add a translation result to the table その他の表記.

Finally, any boundary cases can be caught with the table その他の表記 and the history of translations for boundary cases will be tracked on the table.
(This proposal requires the change of the current localization workflow to check the table その他の表記 when a translator wonders whether the term should be translated into Japanese or not.)

Attention: The update of the table その他の表記 should only be made for boundary cases, not for common cases of the translation. (So the future workload for the table maintenance will be small enough for us). It will not be an inclusive list of k8s terminologies such as zh-cn team's one.

Note: The scope and the effect of changes which may be made for the issue, will be limited in the localization guideline in Japanese. You are welcomed to join the conversation but be sure to talk with Japanese.

Robot

/area localization
/language ja

[Okabe-Junya]

/priority backlog

[Okabe-Junya]

Note: 日本語のローカリゼーションと日本語記事の改善に特化した提案内容であるため、ここでは日本語でのやり取りを希望します。

こちらを英語で記載して、変更内容の要点を日本語で記載いただけると助かりますmm

[Okabe-Junya]

cc @kubernetes/sig-docs-ja-reviews

[youmeim]

Note: 日本語のローカリゼーションと日本語記事の改善に特化した提案内容であるため、ここでは日本語でのやり取りを希望します。

こちらを英語で記載して、変更内容の要点を日本語で記載いただけると助かりますmm

ありがとうございます。ちょっと取り込んでおりまして...今夜どこかで対応します。

[youmeim]

遅くなりました。

背景

浅知恵ではありますが、本イシューは以下のSlackチャネルでの議論に対応するものです。

https://kubernetes.slack.com/archives/CAG2M83S8/p1734352769400349?thread_ts=1733398007.531449&cid=CAG2M83S8

Kuberneteの技術用語が指し示す範囲が人によって異なる可能性があることにより、Kubernetesの頻出概念以外のKubernetes固有の用語については、PR・レビュー単位で翻訳上の判断をしているのが、日本語ローカリゼーションの現状と言えます。

(マイナーな単語は安直にアルファベットやカタカナ語で表記する結果を招くことが多くなりますが、この問題については本イシューのスコープに含めません)

現状の翻訳フローは上手く動いている一方、過去の記事で「特定の用語をどのように翻訳したか」については、コンセンサスが残っておらず、翻訳対象の記事と原文を比較することでしか判断できません。そのため、特定の用語(例えば Pod Admission WebhookやGuranteed QoS) について、 複数の記事で一貫性のある用語翻訳を実現するためには、レビュアーと貢献者の双方が関連する過去の記事を網羅的にチェックすることが必要となる場合 があります。

特定用語に関する翻訳上の確認点としては

• 過去にKubernetes docsでの翻訳事例があるかどうか
• Kubernetes固有の概念であるかどうか
• 固有名詞とみなせるかどうか

以上のようなものがあり、 翻訳対象の記事にこうした用語が複数含まれる場合には、レビュアー・貢献者双方にとって負荷となり、結果的にローカリゼーション関連のコントリビューションの品質に影響しうる ものと考えました。

そこで、マイナーな用語についての参考翻訳フローを図示することに加え、新語ないしはカタカナ語として新規に訳出した技術用語については、「その他の表記」の表に一覧表として追記していってはどうかというのが、本提案の骨子です。

以下、このイシューで議論したい２つの変更点の提案について説明します。

変更提案1

スタイルガイドの用語の表記に、マイナー用語の翻訳フローの参考として、例えば、以下のような図を掲げてみてはどうでしょう。

（この図は大きすぎるので、もっとコンパクトな表現で良いかも知れません。）

変更提案2

「Kubernetesの技術用語」の翻訳の曖昧さを低減するために、スタイルガイドに次の記述を追加するのはどうでしょう。

• APIリソースの一覧と標準化用語集に用語が掲載されている場合は、掲載されている用語で表記して下さい。
• その他のKubernetes用語は、その他の表記に用語が記載されているかどうかを確認して下さい。
• もし、あなたが新しい用語を翻訳したり、レビュアーとの間で特定用語の翻訳に関する合意をしたら、その結果をその他の表記に追記して下さい。

[Okabe-Junya]

ありがとうございます！

Issueの作成や問題提起など、精力的にありがとうございます :)
以下全て一個人の意見です。

賛成

• 標準化用語集( https://kubernetes.io/ja/docs/reference/glossary/?all=true ) に記載の用語は、その表現に準拠させる
  • ただしその場合は、 https://kubernetes.io/ja/docs/reference/glossary/?all=true の翻訳を完了させることがガイドライン更新の必要条件になると思います
• 同様に、API resourceページへのリンクを記載する
• （強い賛成ではないですが）フローの図を記載する
  • Should: 図を作成する場合は https://kubernetes.io/docs/contribute/style/diagram-guide/ を参考にして、マーメイド記法で埋め込む形にしていただきたいです

懸念・疑問

• "「特定の用語をどのように翻訳したか」については、コンセンサスが残っておらず" は、どこに残っていることが期待されるでしょうか。意思決定の過程は https://k8s.io/ja に載せるものではないため、関連するGit log / GitHub Issue, PR / Slack を調査することが一般的かと思いました（SIG-Docs l10n に限らず、kubernetes community全体を通して）
  • 過去に遡っても、このような意思決定の過程はGitHubないしはSlack上に存在すると思います
    • e.g., [ja] Improvement of Localizing Kubernetes documentation for Japanese  #44938
    • 最初期（5年以上前）でもSlack上でやり取りされています: https://kubernetes.slack.com/archives/CAG2M83S8/p1565141627073900
• "その他の表記" が時間経過とともに増え続けること
  • 元々は https://v1-28.docs.kubernetes.io/ja/docs/contribute/localization/ のように、「頻出単語 」のセクションに加筆していました（≒ 提案内容だと思います）
  • この手のセクションは 削除するコスト >>> 追加するコスト なため、一般的なガイドライン・シンプルなルールを提供するに留めておく方が良いと感じました
    • すべての用語を網羅・列挙することは現実的ではないと思いました
    • @Okabe-Junya の知る限りでは、[ja] Improvement of Localizing Kubernetes documentation for Japanese #45037 以外で削除されたことがないです

[Okabe-Junya]

またwebsite全体で表記揺れがなくなっていることは理想的であり、望ましいです。ただ、OSSである（誰でも貢献可能である）ことやReviewerのリソースを考えると、サイトの隅々まで行き届かせることは現実的ではないため、個人的には（少なくとも）ページ内で表記揺れしていないことを優先させる運用が現実的だと思っています。

もちろん、"Pod / ポッド", "Issue / イシュー"のような頻出単語での表記揺れは避けたいので、このような用語に対してガイドラインを整備したいとは考えています。ただ、Guranteed QoS の訳語まで整備し続けられるかというとかなり怪しいと思います。。

[Okabe-Junya]

/triage accepted

[youmeim]

ありがとうございます。本日午前中いっぱい、所用で席を外します。
一先ず @Okabe-Junya さんの懸念・疑問への回答(IMO)のみ書かせて下さい。

• "「特定の用語をどのように翻訳したか」については、コンセンサスが残っておらず" は、どこに残っていることが期待されるでしょうか。

OSSのローカリゼーション過程のコンセンサスが残るとしたら、コミットログやGithubのようなITS、Slackのような公式のコミュニケーションチャネルになるかと思います。

ここで言いたかったのは「日本語ローカリゼーションチームが、あるKubernetes固有の用語をどう翻訳したか」について、コミュニティ内外に一覧として示す場所を設けてはどうか
(そのために「その他の表記」を活用してはどうか)
ということでした。

したがって、「その他の表記」の表に、日英対訳のコンセンサスを蓄積していくことを提案しています。
(一部主張を取り下げます。下記参照)

追記の対象は、リソースではなく、標準化用語集にも記載されていない、例外的な用語だけです。

[youmeim]

• この手のセクションは 削除するコスト >>> 追加するコスト なため、一般的なガイドライン・シンプルなルールを提供するに留めておく方が良いと感じました

この点については同意です。直近のガイドラインの大幅修正で、この点にだいぶ配慮して頻出用語を削ったことは理解しています。

あえて、例外的用語にかぎった「その他の表記」への追記を提案した意図は次の通りです。

(一部主張を取り下げました。下記参照）

• k8s用語ではアカデミア＆大手ベンダー主導で用語を日本語化するインセンティブが働きにくいため、 コミュニティの側で用語日本語化のイニシアチブを取るべきではないか
• そして日本語訳を決めた(標準用語以外の)用語については、一覧表にした方がよいのではないか
• コミュニティで「訳語の決め 」の範囲と基準を明示することで、クラウドネイティブ界隈のカタカナ語＆アルファベット表記を減らす足がかりにできないか

例えば、Pod Security Standardは、リソースでも標準用語でもない例外的なk8s用語ですが、「Podセキュリティ標準」として訳すコンセンサス(用語の決め)が成立したので、「その他の表記」に追記するといった運用を想定しています。
この一覧表は、日本語ローカライザのためだけのものではなく、日本語でk8s関連の記事を書く一般のユーザーを念頭に置くものです。

日本語で技術文書や書籍を執筆するライターやエンジニアは、k8s用語を日本語表記する際のリファレンスとして、翻訳ガイドラインと「その他の表記」を確認することができるでしょう。
この時「その他の表記」に和訳語があれば、ドキュメンテーション以外の場所で書く記事に、安易に横文字を垂れ流さずに済むわけです。

個人的には、「その他の表記」のメンテナンスコスト増よりも、カタカナ語&アルファベット用語の氾濫による日本語話者の認知コスト増を懸念していて、こうした一般ユーザーの認知コストの低減をはかるうえで、私達にしかできないことがあるのではないかと考えています。

[youmeim]

自分で書いた直前のコメントを後から眺めてみて、「この議論をこの文脈で収束させるのはムリだな」と感じました。
直近のコメントに含まれる「その他の表記」の表に関わる主張を取り下げます。
（高卒/専門卒で実務数年くらいのエンジニアが「技術文書を日本語で読みたい」という時に、(翻訳の質はともかく)日本語で概念を理解できるドキュメンテーションが存在することは重要と捉えていますが、この課題についてこの場で話題を提供する意味は極めて薄いと感じました...)

このイシューはあくまでも k/website のローカリゼーション作業の効率化・品質向上を目的とする内容に限った提案とし、その他の私信については他の場で共有することにしたいと思います。

[youmeim]

変更提案１のフローチャートについては、「その他の表記」のような翻訳対照表があることを前提とした判断支援ツールを意図していましたので、現時点では不要と考えます。

したがって、今回の変更提案は「変更提案２」に関わるもののみにまとめ、次のように組み直したいと思います。

【改】変更提案2

「Kubernetesの技術用語」の翻訳の曖昧さを低減するために、スタイルガイドに次の記述を追加します。

• APIリソースの一覧と標準化用語集に用語が掲載されている場合は、掲載されている用語で表記して下さい。
• その他のKubernetes用語については、固有名詞であるものは原則アルファベットで表記して下さい。
• 新しい用語を日本語として翻訳する際は、レビュアーやそのコンポーネントを熟知した人に意見を聞いて下さい。kubernetes-docs-ja チームは、あなたのコメントを歓迎します！

[youmeim]

本件については Okabe-Junya さん以外のご意見も伺ってみたいですね...

[Okabe-Junya]

【改】変更提案2

「Kubernetesの技術用語」の翻訳の曖昧さを低減するために、スタイルガイドに次の記述を追加します。

• APIリソースの一覧と標準化用語集に用語が掲載されている場合は、掲載されている用語で表記して下さい。
• その他のKubernetes用語については、固有名詞であるものは原則アルファベットで表記して下さい。
• 新しい用語を日本語として翻訳する際は、レビュアーやそのコンポーネントを熟知した人に意見を聞いて下さい。kubernetes-docs-ja チームは、あなたのコメントを歓迎します！

SGTMです！

本件については Okabe-Junya さん以外のご意見も伺ってみたいですね...

#49285 (comment) で team: sig-docs-ja-reviews 宛にメンションをしているので、誰か反応すると思います。。（どうしても難しい場合はSlackで明示的にメンションしてください）
チームメンバーの実態は、以下で管理されています

https://github.com/kubernetes/org/blob/eb5db1555f236e90181c2ff99b16a15f974d553a/config/kubernetes/sig-docs/teams.yaml#L141-L152

[youmeim]

#49285 (comment) で team: sig-docs-ja-reviews 宛にメンションをしているので、誰か反応すると思います。。（どうしても難しい場合はSlackで明示的にメンションしてください） チームメンバーの実態は、以下で管理されています

https://github.com/kubernetes/org/blob/eb5db1555f236e90181c2ff99b16a15f974d553a/config/kubernetes/sig-docs/teams.yaml#L141-L152

ご案内ありがとうございます！
急いで話すことでもありませんので、しばらくオープンにしておきます。

受け持っている記事の処理がひととおり終わる頃を見計らって、（忘れないように）PR立てます。