PHP 8.4の翻訳作業ではじめてPRを出す為の手順
概要
PHP8.4が2024/11/21にリリースされました! やった~!🎉
PHP: PHP 8.4 Release Announcement
リリースに伴い、PHP8.4の翻訳作業があるのですが、まだ一部の翻訳が完了してない状態です。
KentarouTakedaさんがXでお声がけをしているのを見て自分も翻訳に参加しようと思い、PRを出そうと思った次第です。
しかし、そもそもこれまで自分がOSSにPRを出す機会がなく、やり方も全然わからなかった為、自分のようにはじめてOSSにPRを出す方向けに手順を残しておきます。
※この記事の構成は asumikan さんのIssueのコメントを参考に記事を書いているのでここで謝辞を残しておきます! ありがとうございます! 🙏🦀
step1 📝php/doc-jaで翻訳作業を行うにあたってドキュメントを先に読む
いきなり「よし!翻訳するぞ!」と動く前に一呼吸いれて、php/doc-jaで行われてきた翻訳作業での対応手順や用語を先に読んでおきましょう。翻訳作業は最終的に他の方にもレビューしてもらい、approvedをもらってからマージされます。
その際に事前に前提知識を合わせておくとPRを用意する際にも混乱が減るので以下のドキュメントをまずは一読しておきます。
step2 💪localで動作確認する為に jdkfx/phpdoc リポジトリをgit cloneする
はるきさんがphp/doc-jaを翻訳する際に、ローカル環境で簡単にPHPマニュアルが見れるように jdkfx/phpdoc を用意してくださったのでこちらのリポジトリをgit cloneします。
forkしてきたらリポジトリをlocal環境で落としてきてmakeコマンドを実行していきます。
git cloneする
git clone git@github.com:jdkfx/phpdoc.git
翻訳で必要なファイルをsetupし、buildしていきます。
cd phpdoc
make setup
make build
make xhtml
buildが完了したら、make openを実行して、ローカル環境でPHPマニュアルのページが見れる事を確認します。
make open
これでlocal環境で動作確認する為の順番は完了です。
step3 🏃♂️翻訳対象のPRを選ぶ
翻訳状況については以下のIssueでまとまっています。
PHP 8.4 マニュアル翻訳状況
(2024/11/24現在だとまだ30個以上はチェックがついてない状態です。)
IssueでチェックがついてないPRを見て翻訳対応のメソッドをみていきます。
KentarouTakedaさんが翻訳の難易度を絵文字で表現してくださっているのでまずは🔰の初心者マークがついているメソッドを選んで翻訳作業に参加してみましょう。
今回は自分が実際に翻訳作業をした「DOMImplementation::createDocument()」を参考に説明します。
step4 👀翻訳対象のPRの変更が最新か?を一応確認する
対象のPRはマージされたのが1ヶ月前とかになっていると、その後軽微な修正がphp/doc-enに反映されている場合対応が漏れてしまうので、対象の変更が最新のコミットかを確認しておきましょう。
File Changedタブからファイルパスを確認します
ファイルパスは「reference/dom/domimplementation/createdocument.xml」になっているのを確認します。次にphp/doc-enの「reference/dom/domimplementation/createdocument.xml」のhistoryを確認します。
historyを見ると今回、翻訳対象のPR(#3901)が一番上にあるので大丈夫そうです。
step5 📑php/doc-jaをforkして翻訳作業を行う
php/doc-jaをforkします。
forkできたら自分のlocal環境にgit cloneしてきます。
(例)
git clone git@github.com:<YourGitHubName>/doc-ja.git
PRを用意する為にブランチを切って翻訳作業を始めます。
Fork元のリポジトリにPRを出す為にFork元のリポジトリをupstreamリモートとして設定します。
git remote add upstream git@github.com:php/doc-ja.git
git remote -vで追加されているかを確認します。
# git remote -v
origin ssh://git@github.com/Fendo181/doc-ja.git (fetch)
origin ssh://git@github.com/Fendo181/doc-ja.git (push)
upstream git@github.com:php/doc-ja.git (fetch)
upstream git@github.com:php/doc-ja.git (push)
PRを送る前に、Fork元(php/doc-ja)の最新のコードを取得しておきます。
git fetch upstream
ローカルのmasterブランチにマージ
git checkout master
git merge upstream/master
これにより、ローカル環境が最新状態になります。
この状態で翻訳する作業ブランチを用意しましょう。作業ブランチ名に関しては翻訳元PRの作業ブランチを参考にしてもいいです。
git checkout -b 'createdocument-84'
この状態で翻訳作業を開始します。
翻訳作業をする際には基本的にはdoc-enを比べて、追加修正ならブロックを適切な場所において日本語訳にします。翻訳する単語が難しいのが出てきたら、doc-enでも同じ単語を使っているページを探して、既存のPHPマニュアルではどんな風に翻訳しているかを見にいきます。
また、すでに日本語訳がある場合はメンションしてお知らせしましょう。
step6 ⚖️EN-Revisionをあわせる
PHP公式ドキュメントの日本語版（php/doc-ja）が英語版（php/doc-en）の最新状態に追従する為、EN-Revisionをあわせます。
EN-Revisionはなにか? というとPHPドキュメント内で使用されるメタ情報の一つで、そのドキュメントが英語版のどのコミット（リビジョン）を基にしているかを示すものです。
翻訳元のEN-Revisionはdoc-baseのrevcheck.phpを使って確認します。
このdoc-baseはstep1で用意したjdkfx/phpdoc内にあるのでこちらから実行して確認してみましょう。
まずは最新の変更を取り入れてからコマンドを実行します。
cd jdkfx/phpdoc/doc-base
git pull origin master
php scripts/revcheck.php ja > revcheck.htm
実行が完了すると revcheck.htmが生成されるのでファイルをブラウザで見てみます。
今回担当したドキュメントは createdocumentなので、ブラウザ内で文字列検索をすると以下の項目がヒットしました。
ここの「Copy」をクリックしたリビジョンを翻訳PRにも反映させます。
変更する行は <!-- EN-Revision:から始まるところです。
こちらの作業はなくても、php/doc-jaのmainteinerの方がコミットしてくれますが、なるべく追加しておくと作業が減るので対応しておきましょう。
step7 ✏️コミットを積んでPRを用意する
以上の翻訳作業と、EN-Revisionを合わせてプレビューで問題ないことを確認します。👌
プレビューの確認としてはstep1で整えたjdkfx/phpdocで確認します。
- (1)
php/doc-jaで編集したファイルを、jdkfx/phpdoc内の同名のファイルにも反映させる - (2)
jdkfx/phpdoc内でbuild/xhtmlを生成
make build
make xhtml
- (3)local環境のPHPマニュアルのプレビューでちゃんと反映ができているかを確認しましょう。
make open
問題ない事を確認したらコミットを積みましょう。
コミット後はpushします。
git push origin createdocument-84
push後にPRを作成するURLをクリックすると、php/doc-jaのmasterのブランチがマージ先になっている事を確認します。
ここまで出来たらPRの概要を埋めて「Ready for review 」にします!
翻訳作業の手順は以上です! お疲れ様でした!
レビュー依頼についてはPRを作成状態にしておけば、php/doc-jaのmainteinerの
どなたが見てくれます!🙏
おわりに
php/doc-jaで翻訳する作業の手順をまとめました!
ちなみに上記で紹介したPRは現在、無事にマージされてPHPマニュアルでも見れます! (嬉しい~! 🎉)
自分と同じようにOSSで協力したいけど、手が出すのが少しハードルが高い!と思っている方はぜひ、こちらの翻訳作業に参加してみましょう!
Discussion