Kubernetes公式ドキュメント内リンクを/ja/docs/に置き換える
はじめに
#kubernetes-docs-jaチャンネルの質問をきっかけとして、Kubernetes公式ドキュメント日本語版の中のリンクの話をしてみようと思いました。
日本語のKubernetesのドキュメントを確認していると、リンクの先が日本語のドキュメント
/ja/docs/...になっているものと英語のドキュメント/docs/...になっているものの2通りがあるのですが
この使い分けは決まっていますか……？(リンク先に日本語記事があるかどうか？)
https://kubernetes.slack.com/archives/CAG2M83S8/p1613399049017700
立場
私は1年ほどreviwerとして活動した後、現在は病気療養のため離脱しています。翻訳はしない。レビューもしない。でも無理のない範囲で何かしらしたいと思い、自由に動いています。
昨日、good first issueがたくさんできたというアナウンスがありました。バリバリ活動していた頃にIssueを作るためのツールを開発し、一昨日いんだくたーさんに引き継いでいました。
リンクの使い分け
Slackでいんだくたーさんが回答していた通りです。
はい。英語の場合には
/enがないのでjaは日本語があるもののみです。
ただし、リンクの更新はベストエフォートでやっており、リンク先が翻訳されていても原文にリンクされたままのものがたくさん（？）ありそうです。
リンクの更新
というわけで、リンクを置き換えていきましょうか。
翻訳済みページ一覧の抽出
git ls-files content/ja/docs \
| grep -v glossary \
| sed -e 's/content//' -e 's/\.md$/\//' -e 's/\/_index//'
出力は以下のようになります。
/ja/docs/
/ja/docs/concepts/
/ja/docs/concepts/architecture/
/ja/docs/concepts/architecture/cloud-controller/
/ja/docs/concepts/architecture/controller/
/ja/docs/concepts/architecture/master-node-communication/
/ja/docs/concepts/architecture/nodes/
...
リンクの確認
一覧から任意のページを取り上げます。
# /ja は入れない
export TARGET_PAGE=/docs/concepts/architecture/nodes/
置換対象のリンクがあるか確認します。
git grep $TARGET_PAGE content/ja/docs/ | grep -v "/ja$TARGET_PAGE"
出力は以下のようになります。
content/ja/docs/tasks/run-application/force-delete-stateful-set-pod.md:Kubernetes(バージョン1.5以降)は、Nodeにアクセスできないという理由だけでPodを削除しません。到達不能なNodeで実行されているPodは、[タイムアウト](/docs/concepts/architecture/nodes/#node-condition)の後に`Terminating`または`Unknown`状態になります。到達不能なNode上のPodをユーザーが適切に削除しようとすると、Podはこれらの状態に入ることもあります。そのような状態のPodをapiserverから削除することができる唯一の方法は以下の通りです:
１行ヒットしました。
Issueの作成
Issueを作成しましょう。reviewerに/triage acceptedしてもらう運用に変わっているのが面倒ですね。Issueを作るたびにSlackに投稿するのがよいのでしょうか？
Issueの例： https://github.com/kubernetes/website/issues/26572
ハッシュフラグメントの扱い
ハッシュフラグメントは原文に合わせて英数字とします。日本語にしてしまうとリンクを共有するときに%エンコードされてしまってイケてないためです。これはreviewer内でも議論済みです。IssueなのかSlackなのかぱっと出せませんが。
たとえば#ノードの状態といった形式ではなく#node-conditionとします。今回の例では原文の値自体がおかしく#conditionが正解のようです。
このあたり私はうまく説明できません。誰かこちらのページに追記してくださると幸いです。
注意点
この方法ではURL末尾に/がないリンクは拾えません。grepするときに/を含めないようにすればよいのですがノイズが多くなるかもしれません。
/ja/docs/conceptsなどの親階層を調べようとすると子階層もヒットするので工夫が必要です。
また、Pull Requestを作成する際は2020/2/16時点ではdev-1.18-ja.2ブランチ宛にお願いします。不明点などあれば#kubernetes-docs-jaチャンネルで質問すれば誰か拾ってくれると思います。
おわりに
OSSコントリビューション初心者の方でもそこまで難しくないと思います。ぜひチャレンジしてみてください！
Discussion