2024-07-10追記
昨年度末にリリースされたv17から、Angularルネッサンスと称した取り組みの一環で、ドキュメントサイトの一新が行われています。
これにより、今後は angular.io(v17.angular.io/docs) から angular.dev にドキュメントを置き換えていく動きがあるようです。
angular.dev ではまだローカライズの仕組みが整っていないため、本記事はv17までの angular.io におけるローカライズ活動の紹介ということに留意してください。
-
Discord | #angular-ja翻訳 | Angular日本ユーザー会 より
(ということで、v17以前の翻訳活動自体はまだ続けられています！)
こんにちは、あかいです🐗
本記事は Angular Advent Calendar 2022 の5日目の記事です！！ 遅刻してスミマセン😢
4日目は@Jialipassionさんで6日目は@beltway7さんです！
Angularには非常に丁寧で網羅性のある、高品質なドキュメントがあります。
これは、Angular開発チームと有志の編集者たちによって管理されているドキュメントプロジェクトです。
ドキュメントは英語で書かれていますが、
Angular 日本語ドキュメンテーションのドメインに、日本語化されたものがあります。
angular.jpは、主に有志の開発者たちの手で管理されており、
angular.ioに追従するために日々コミットがなされています。
本記事では、angular.jpに日本語訳を提供して貢献するために必要な技術的手法と、その手順をお伝えいたします！
みなさまもぜひ、翻訳をしてangular.jpにコントリビューションしましょう！
翻訳のための必要技術要件
angular.jpは、Angularを用いて構成されており、
ドキュメントの動作環境をローカルで構築するために、gitコマンドなどを使います。
よって、次のコマンドが動く環境と知識が必要です。
- git
- yarn
また、angular.jpのリポジトリはGitHubで管理されているため、
GitHubアカウントも必要になります。
リポジトリのクローンと大本リポジトリの同期
まずはangular.jpのリポジトリをローカル環境にクローンしましょう。
$ git clone git@github.com:angular/angular-ja.git
angular.jpは、angular.ioに対して、git submoduleを利用することで大本リポジトリの同期を実現しています。
そのため、リポジトリをクローンしたあとはsubmoduleでのsyncが必要になります。
リポジトリディレクトリ内に移動して、次のコマンドで同期とビルドを完了してください。
(ちなみに5分くらいかかりました)
$ cd angular-ja
$ yarn build
これで、翻訳の前準備は大方終わりました。
翻訳箇所の宣言表明
angular.jpは複数人の有志の手によって翻訳されているため、
同時におなじファイルを変更しないよう協調が必要です。
翻訳に入る前に、まずはangular.jpのIssueで翻訳/担当したいページや箇所を表明しましょう。
(このとき、PRが出せる予定日時を添えてあげると丁寧かもしれません。)
(現在は基本的に、翻訳が必要なページはすでにlacoさんがIssue化していますので、
新しくIssueを作るのではなく、既存のIssueにコメントして意思表明をする形になると思います。)
しばらくすると、lacoさんからお返事をもらえるので、それから翻訳作業に入ってください。
翻訳作業とコミット
angular.ioはAngularで構築されています。
yarnを利用してサービングを行うことで、翻訳したファイルをWeb上でリアルタイムプレビューできます。
http://localhost:4200/ でAngularのドキュメントが閲覧できるようになります。
$ yarn start
それではお待ちかね、実際の翻訳作業です。
Issueで宣言した担当ページをブラウザで確認したら、URLから該当のファイルを探し出します。
- 翻訳するファイルは
/aio-ja/content/**配下にあります - もしも該当ファイルが存在しない場合、originディレクトリから新しくファイルをコピーする必要があるかもしれません
ファイルを変更して保存すると、リアルタイムでブラウザのリロードが走り、ドキュメントが翻訳されているのが確認できるかと思います。
翻訳が終わりましたら、commitしてpushし、PRを作成しましょう。
$ git add .
$ git commit -m 'translate: animation.mdの翻訳 (#111)' # コミット文はもちろん書き換えてネ
PRを提出し、レビューやフィードバックがあれば、あらたに修正をコミットして再度PRを行ってください。
おつかれさまでした！
その他
CLAへのサインイン
PRを作成してしばらくしたあと、google-claというコメントがPRにつくことがあります。
英語のコメントで説明が書いてあるのですが、これはCLA(Contributor License Agreement)と言って、
初めてのコントリビューションするユーザーのPRに出てきてCIを落とします。
google-claのコメントがついてCIが落ちているときは、提示されたURLにアクセスしてCLAを完了し、
I signed it!などとリプライをすることでCLAが完了してCIが通るようになります。
CONTRIBUTING.md
筆者のこの記事を読まなくても、実は貢献のための詳細な情報はこちらにまとまっております！
翻訳にうつる前に、かならず目を通しておくようにしましょう。
Discordコミュニティについて
翻訳についての議論は、Angular日本ユーザー会のDiscordの翻訳チャンネルでも行われています。
だれでも参加可能ですので、この機会にぜひjoinしましょう！
(こちらのサーバーは、翻訳以外のものでもAngularの話題ならなんでもあります！)
さぁ、キミも一緒にAngular日本語ドキュメントの翻訳に協力しよう！