概要
CakePHP4がリリースされましたが、
CakePHP4の英語ドキュメント
https://book.cakephp.org/4/en/index.html
に比べ、CakePHP4の日本語ドキュメント
https://book.cakephp.org/4/ja/index.html
はまだ、CakePHP4に対応していない箇所が多く、CakePHP3の内容のままです。
実装に携わった箇所からCakePHP4の翻訳を進めているので、
その手順をまとめておくことにしました。
翻訳手順
CakePHPドキュメントは、以下のGitHubリポジトリで管理されています。
https://github.com/cakephp/docs
ドキュメントページから直接修正
typo等の簡単な修正であれば、ドキュメントページから直接修正するのが早いです。
以下で詳しく解説されています。
https://qiita.com/Gro/items/f0b6846ff2a9498dcad3
※現在は、事前にforkしなくても、自動的にforkまでやってくれるようです。
※cakephp/docsにマージできる権限があると、PR作成されずに直接マージされてしまうらしい。
git cloneして修正
ドキュメント全体を更新する場合は、実際に生成されたhtmlの体裁確認が必要になるため、git cloneしてhtmlをビルドして確認します。
参考にしたもの
-
https://github.com/cakephp/docs/README.md
- Dockerでのhtmlビルド方法が記載されている
-
https://devblog.thebase.in/entry/2018/02/13/163843
- Dockerでのhtmlビルド方法について詳しく解説されている
手順
- リポジトリをfork
- forkしたリポジトリをclone
git clone git@github.com:[your-name]/docs.git
- 4.xブランチに切り替え
git checkout 4.x
- 4.xをベースにブランチを作成
git branch 4.x_ja_core-libraries_time
- 翻訳作業を行い、commitする
- Dockerでhtmlをビルド
- 詳細手順は後述
- forkしたリポジトリにpush
git push origin 4.x_ja_core-libraries_time
- GitHub上でPRを作成
Dockerでのhtmlビルド手順
※最初の1回目はdocker buildが必要です。
cd docs
docker build -t cakephp/docs .
Mac、Linuxでのビルド
docker run -it --rm -v $(pwd):/data cakephp/docs make html-ja
Windowsのビルド
git bashの場合
docker run -it --rm -v /$PWD:/data cakephp/docs make html-ja
Power Shellであれば、Windowsのフルパスを指定すればビルドできます。
docker run -it --rm -v C:\Users\your-name\docs:/data cakephp/docs make html-ja
docs/build ディレクトリにhtmlが生成されるので、ブラウザで確認します。
forkしたリポジトリの更新手順
PRがマージされると、4.xブランチが更新されるので、forkしたリポジトリにも反映しておきます。
https://github.com/cakephp/docs をupstreamとして登録します。
git remote add upstream git@github.com:cakephp/docs.git
forkしたリポジトリを更新します。
git pull upstream 4.x
git push origin 4.x
翻訳時に気を付けていること
日本語ドキュメント
https://book.cakephp.org/4/ja/index.html
はまだCakePHP3の内容のままなので、
英語ドキュメント
https://book.cakephp.org/4/en/index.html
の内容を参考に、翻訳していきます。
git cloneした場合は、enディレクトリとjaディレクトリの差分を比べるのが良いと思います。
特に以下の点は変更されているので注意して確認します。
- 3.xの各マイナーバージョンごとの変更点
- deprecated等も含む
- コード例
- 関数の型宣言等のPHP7対応
翻訳の単語選定に迷った場合ですが、私は、
jaディレクトリ内をそのキーワードで検索して多い方を採用しています。
（多少不自然な訳でも、英語原文に忠実に訳しているパターンが多いようです）
Google翻訳等の翻訳ツールを併用することが多いと思いますが、
最近出たDeepL
https://www.deepl.com/translator
は、翻訳精度が高いのでオススメです。