Kubernetesドキュメントの日本語翻訳に関わり始めた
1行で
カジュアルな気持ちでk8sの翻訳に関わり始めたよ。
背景
YAPC KYOTO 2023はYouTubeで視聴していて、Linux Conferenceの主催側立場だったりした頃を思い出したり、Debian ConferenceやRuby会議も楽しかったなーなどと感慨にふけっていた(今年のRuby会議はちょっと行きたいなと思ったんだけど、業務とつなげるのが現状では難しそうなのもあって見送り)。
発表はどれも印象深かったのだけれども、最後のLTで@nasa9084さんの「Kubernetesの翻訳協力者募集！」を聞いて「Kubernetes使える人は英語で特段問題なさそうだなぁ」と感想を呟いたところ、@nasa9084さんに拾っていただいて反応をもらった。
そもそも翻訳をできる人は日本語のドキュメントを必要としてないので、コントリビューターが足りないのです・・・
— nasa9084@某某某某(0x1d) (@nasa9084) 2023年3月19日
なるほどなるほど。
ちょうどk8sコンテナまわりはちゃんと知識として覚えておこうという気持ちがあったので、翻訳に参画することを決めた。もともとDebianでインストーラ・apt・dpkg・各debconfメッセージ、あとはDebianのWebページ類etc、といろいろ和訳はしていたので、翻訳自体への抵抗はない。
「やってみたい」「やろうかな」…そんな言葉は使う必要がねーんだ なぜならその言葉を思い浮かべた時には！ 実際にgit cloneしちまってもうすでにエディタを開いているからだ！ 「WIP」「PRした」なら使ってもいいッ！
準備
それはさておき、とりあえずGitHub https://github.com/kubernetes/website/ からいろいろと見ていく。
- コンテンツはMarkdown。
- content/enに原文、content/jaに日本語が置かれている。
- poファイルや原文バージョン指定などはしておらず、疎な関係にある。つまり、原文が変わってもGit履歴と差分追跡を人力でやらないといけない(たぶん。ツールは何か作れるだろうけれども)。
- https://kubernetes.io/ja/docs/contribute/localization/ に参加方法や翻訳手順が書かれている。
- 日本語ファイル間でけっこう表記揺れが多い。上記ページにスタイルガイドはあるが、遵守されていない印象。
- 訳されていないページはそれなりに多い。
まずは https://github.com/kubernetes/website/blob/main/README-ja.md の手順に従って、Dockerを動かしてローカルでWebドキュメントを見られるようにした。変更するとすぐに反映される。
まずは後ろからやっていけば作業競合はしないだろうと、手元でブランチを切って、docs/tutorials/services/pods-and-endpoint-termination-flowの翻訳を開始。
- 手元に展開したwebsiteワークフォルダでブランチを切る。
- content/en/docs/tutorials/services/pods-and-endpoint-termination-flow.mdをcontent/ja/docs/tutorials//services/pods-and-endpoint-termination-flow.mdにコピーする。
- 原文状態のまま追加・コミットする(翻訳化差分をとりやすいようにしておく)。
- 翻訳する。
- プレビューしたり校正チェックしたりする。
- コミットする。
まだIssueやPRにはしていない状態。
注意することとして、コミットのメールアドレスは重要で、後々このメールアドレスに紐付いてCLAの契約をすることになる。到達可能でかつ契約アドレスとして問題ないアドレスにしよう。
CLA自体はIndividualを選べば会社アドレスでも問題はないが、複数アドレスを使い分けている環境でうっかり混ぜてしまったときには、履歴変更の必要に迫られて少々面倒なことになると思われる。
翻訳手法
後述するCLAの契約では、original creationであることが求められているため、DeepL・Google翻訳・ChatGPTなどの機械翻訳のコンテンツは避けるべきである。そういうのは読者が使えばいいわけで、ドキュメントについて機械翻訳をPRするのは好意的に見ても「誤った善意」😩と言える。
ということで、翻訳自体は昔ながらのスタイルとなる。EmacsにSKK、辞書はEmacsのlookupからebnetdでリーダーズプラス、広辞苑、類似語辞典。k8s固有の語以外に難しい単語は出てこないので、辞書の登場は少ない。
ほかを見ても原文コメント残しはしないようなので、愚直に訳しては原文段落を消し、という作業をしていく。原文は技巧的難読ではないのだけれども、文をつなげすぎて読みにくいと感じた。とはいえ、超訳は私は好みではないので、あくまで原文を尊重しながら、読点や文のつなげ方・配置によって原文の意図が伝わるように配慮してみている。
機械翻訳を避けるとはしているが、「一応訳してみたけれども、どうにも原文の意味が取れないぞ……？」というところについては、DeepLにその箇所を入れてみて、ニュアンスに根本的な違いがないかを比較したりはしていた。だいたいは原文が無駄に読みにくくしているところだったりする。
校正
プレビューはDockerで構築したWebサーバーからすぐに見られるので、体験として良い。
https://kubernetes.io/ja/docs/contribute/localization/ の表記ルールがカッコ半角などいくぶん特殊で、何も考えずにいると違反しそうだなと思ったので、textlintの校正ルールを整備することにした。
textlint --rule @kmuto/preset-kmu-kubernetes ファイルで検査できる。デフォルトでいろいろな校正ルールも含めているのでfalse alarmは出やすいのだが、一応気をつけるポイントは入れていて、自分自身で試す限りはこれでひとまず間に合っている。termcheckも仕込んであるので、「Kubernetes」のタイプミスも発見できるぞ。
原文が……
さて、訳していったところ、類似の文が2回続くところがあって、これはどう見ても最初の文を消し忘れたんじゃないか？という確信が出てきた。履歴を見ても昔からこうだったらしいが。
ということで、Issueで報告。これがK8sのcontributeデビュー。
シュッとバグ認定されて、2日後には修正反映された👍
メッセージ内で/language、/triage、/assign、/closeとCIボット向けの命令が使われるのが官僚的ビッグプロジェクトっぽさがあると感じたけど、そういえばDebian BTSもtagsだのseverityだのいろいろあるなと思い出した。
Issue化
k8sの翻訳は、最初にFeature Request Issueとして何を追加したいか(What would you like to be added)を示す必要がある。実際には、単にURLを示してこれを訳すぜという宣言でよい。Commentsにボット向け命令として「/language ja」(日本語である)、「/assign」(自分自身が作業する)を入れる。
よっしゃ、やるぜー。なお、なぜこのIssueで「/language ja」が2通目にあるかというと、もう元Issueのほうを直しちゃったけどタイプミスしたからである……。
さて、Issueを出した後はPRの前に誰かコーディネータに作業トリアージしていただく必要がある(トリアージ待たずにPRを出してもいいみたいだけど一応)。
この段階になると日本語コミュニティに参加する頃合いだなと判断して、KubernetesのSlack #kubernetes-docs-ja に https://communityinviter.com/apps/kubernetes/community 経由で入り、ご挨拶。とはいえ、反応くださったのは@nasa9084さんだけだった……🥺
Issueのほうは、Otaさんからトリアージをいただいて、晴れてPRできるようになった👍
基本的にはこのPRが追加するもの(今回はyamlファイルも翻訳対象だったのでそれも記載)を記載するだけ。一応Issueの番号も入れておいた。
レビューアのスタンスとしては、メッセージが英語で書かれていたら英語で、日本語で書かれていたら日本語で、とのことなので、「(表現に関わるため、この翻訳についてのデイスカッションは日本語を希望します。)」という一文を付けた。
CLAへの同意
ここが人によってはカジュアルな参加の壁になりそうなところで、PRを実行すると、まだCLA同意していないときにはlinux-foundation-easyclaボットからCLAへの同意が求められる。CLAとはContributor License Agreementのことで、主にコードパッチに対して本人が正当なcopyrightオーナーであってパクリではなく、誰の権利も特許も侵害していませんし、取り込まれた後もその使用について制限しませんよという契約となる。いろいろと法的厄介実績のあるLinux Foundationらしいなぁと思う。
とはいえ、やることとしては以下の手順で進めばよい。
- 「Please click here to be authorized」をクリック。
- Linux Foundation: EasyCLAをGitHubでAuthorizeする。
- Linux Foundationページにリダイレクトされるので、個人活動なら「Proceed as Individual Contributor」をクリックする。
- CLAを読む。
- DocuSignにFull name(名前)・Mailing Address(住所)・Country(国、Japan)・E-Mail(コミットメールアドレスと同じもの！)を記入する。
- 署名を入れる。名・姓はともかく、イニシャルは実際使ったことがないなぁ……と思いつつそのままにした。署名は、スタイルの選択(デフォルトで名前から作られる画像)、手書き(マウスだと辛い)、アップロード(自分で画像を用意)から選べる。マウスだと辛すぎたので、タブレットで書いて400x145ピクセルの画像化してアップロードした。
- 署名すると、GitHubのPRに戻ってきて「COVERED」となり、コミットが認可されている状態になる。
これらの手順はさっさと終わらせて登録してしまったのだけれども、ガイドのためにキャプチャしておけばよかったな。
レビュー
その後はk8-ci-robotさんから1st PRについてめちゃくちゃ誉められる🥰 皆も承認欲求を満たすために1st PRしていってほしい。
netlifyによるプレビュービルドが行われると、あとはレビューア待ち。今回は@Arhellさんが@atoato88さんをassignしたけど、@nasa9084さんがまずはレビューしてくれた(日本語で)。
- 日本語ページがあるときには/ja/〜とする。なるほど確かに。コンテンツネゴシエーションじゃないんだった。
- サービスは基本Service。
レビュー提案をマージしてapprovedはいただいたけれども、まだレビューアが必要なのと、lgtmラベルが必要らしい。ということであとは待ち、となった。
感想
- CLA以外はそんなに変わらない
- 原文がそもそもわかりにくいかも
- レビューアの人数が必要なのはわりと負担重そう
ともあれ、地道に1つずつ訳していこう。今は、2つ目の長文記事訳のPRは提出済みで、3つ目のさらに長文のに着手したところ。
やっていき〜。