§Play ドキュメント翻訳
Play 2.3 以降、ドキュメント翻訳者たちが Play ドキュメントを翻訳し、そしてそれを更新し続けるための助けとなるインフラが提供されます。
ドキュメントガイドライン で述べられているとおり、Play のドキュメントは外部ファイルに抽出されたコードサンプルと共に、markdown フォーマットで記述されています。Play ドキュメントの markdown 部分は翻訳できるようになっており、また英語版ドキュメントのコードサンプルを翻訳したドキュメントに含めることができるようになっています。この仕組みは、翻訳者たちが翻訳の品質を保つ手助けとなります - 翻訳された表現は手作業でメンテナンスしなければならない一方、コードサンプルは Play プロジェクトの主要な部分として更新され続けます。
この仕組みに加えて、Play は翻訳されたドキュメントの完全性を検証する機能も提供しています。この機能には、コードスニペットへのリンクも含め、翻訳ドキュメント内のすべての内部リンクの妥当性検証が含まれています。
§前提条件
activator または sbt がインストールされている必要があります。翻訳するブランチがチェックアウトされた Play リポジトリの clone があるととても便利なので、何らかのコピーと共に始めましょう。
まだリリースされていないバージョンの Play ドキュメントを翻訳する場合、まずそのバージョンの Play をビルドして、ローカルマシンに publish する必要があります。これは、以下のように実行します:
./build publishLocal
上記コマンドは Play プロジェクトの framework ディレクトリで実行してください。
§翻訳環境のセットアップ
以下の構成に従って新規 SBT プロジェクトを作成します:
translation-project
|- manual
| |- javaGuide
| |- scalaGuide
| |- gettingStarted
| `- etc...
|- project
| |- build.properties
| `- plugins.sbt
`- build.sbt
build.properties は、例えば以下のような SBT バージョンを含んでいなければなりません:
sbt.version=0.13.8
plugins.sbt は、例えば以下のような Play ドキュメント用 sbt プラグインを含んでいなければなりません:
addSbtPlugin("com.typesafe.play" % "play-docs-sbt-plugin" % "2.6.x")
最後に、build.sbt で以下のようにして Play ドキュメントプラグインを有効にします:
lazy val root = (project in file(".")).enablePlugins(PlayDocsPlugin)
これで翻訳を始める準備が整いました!
§ドキュメントの翻訳
まず最初に、ドキュメントサーバから始めます。このドキュメントサーバは、ドキュメントがどのように見えるか確認することができるよう、サーバにドキュメントをアップロードして提供します。これを行うためには sbt または activator がインストールされている必要があります。どちらでも結構ですが、この例では sbt を使います:
$ sbt run
[info] Set current project to root (in build file:/Users/jroper/tmp/foo-translation/)
[info] play - Application started (Dev)
[info] play - Listening for HTTP on /0:0:0:0:0:0:0:0:9000
Documentation server started, you can now view the docs by going to http://0:0:0:0:0:0:0:0:9000
ここでブラウザから http://localhost:9000 を開きます。デフォルトの Play ドキュメントが表示されているはずです。最初のページを翻訳する時がやってきました。
Play のリポジトリから自分のプロジェクトに markdown ページをコピーしてください。ここで重要なのは、プロジェクトのディレクトリ構成が Play のディレクトリと合っていることです。このことにより、コードサンプルの動作が保証されます。
例えば、manual/scalaGuide/main/http/ScalaActions.md から始めることにした場合、このファイルが自分のプロジェクトの manual/scalaGuide/main/http/ScalaActions.md にあることを確認する必要があります。
注意: Play マニュアルを自分のプロジェクトに丸ごとコピーするところから始めるのが魅力的に見えるかもしれません。もしそうする場合、markdown ファイルだけをコピーして、コードサンプルまでコピーしないように気を付けてください。コードサンプルをコピーすると、Play のコードサンプルを上書きすることになり、コードサンプルが自動的にメンテナンスされる利点を失うことになります。
これでドキュメントの翻訳を始めることができます。
§コードサンプルの取扱い
Play ドキュメントには数多くのコードサンプルがあります。 ドキュメントガイドライン で述べられているとおり、これらのコードサンプルは markdown ドキュメントから切り離されており、コンパイル、そしてテストされたソースファイル内に存在しています。これらファイル内のスニペットは、以下の文法を使ってドキュメント内に取り込まれています:
@[label](code/path/to/SourceFile.java)
通常、これらのコードスニペットが Play と共に更新されることが保証されることになるので、翻訳内のスニペットはそのままにしておきたいことでしょう。
時として、コードスニペットを上書きすることが理にかなっている場合もあります。ブロックを使ってドキュメント内に直接コードを埋め込むこともできますし、独自のコンパイルされたコードサンプルとして抽出することもできます。これを行う場合、Play ドキュメントの sbt ビルドファイルをチェックアウトして、コードサンプルをコンパイルするための SBT セットアップ方法を確認してください。
§ドキュメントのバリデーション
Play docs sbt プラグインは、リンクとコードサンプル参照の完全性を保証するため、ドキュメント全体に対してシンプルなテストを実行するドキュメント妥当性検証タスクを提供しています。これは、以下のようにして実行することができます:
sbt validateDocs
Play ドキュメント内にある外部サイトへのリンクを検証することもできます。このタスクは Play ドキュメントがリンクしているインターネット上の多くのサイトに依存し、また実際のところ、この検証タスクはいくつかのサイトの DDoS フィルタを引き起こしてしまうので、別のタスクに切り出されています。このタスクは、以下のように実行します:
sbt validateExternalLinks
§翻訳レポート
Play が提供するもうひとつの便利なツールが翻訳レポートで、これはどのファイルが翻訳されていないか表示したり、翻訳に新しいファイルが含まれている、あるいは翻訳にコードサンプルが見つからないなどの問題も検知します。コードサンプルの追加または削除は何かが変更された兆候であることが多いので、とくに新しいバージョンのドキュメントを翻訳する際に便利です。
翻訳レポートを見るには、(通常と同じように) ドキュメントサーバを起動し、ブラウザから http://localhost:9000/@report にアクセスします。以前にレポートを生成したことがある場合は、デフォルトでこのキャッシュを表示しますが、レポート再生成リンクをクリックすることでレポートを再生成することができます。
§playframework.com にドキュメントをデプロイする
playframework.com は git リポジトリとは別の場所でドキュメントを提供しています。翻訳を playframework.com から提供したい場合、ドキュメントを GitHub リポジトリに配置して、これを playframework.com に追加するよう Play チームに連絡する必要があります。
git リポジトリはかなり特別なフォーマットである必要があります。現在の master ブランチは、最新版開発バージョン Play のドキュメントのためのものです。安定板 Play のドキュメントは 2.3.x のようなブランチでなければなりません。特定リリースの Play に特化したドキュメントは、例えば 2.3.1 のような名前のリポジトリタグから提供されます。
playframework.com はすべてのリポジトリに対して 10 分ごとに git fetch を実行するので、Play チームがあなたの翻訳を提供するよう playframework.com を設定したあとは、GitHub リポジトリに push したあらゆる変更は、おおよそ 10 分以内に拾い上げられます。
§ドキュメントバージョンの指定
play-docs-sbt-plugin のデフォルトは同じバージョンの Play ドキュメントコードサンプルを使って markdown ファイルとして書き戻すので、 plugins.sbt において 2.4.0 を指定している場合、ドキュメントサーバを起動すると 2.4.0 のドキュメントコードサンプルが表示されます。このバージョンは build.sbt 内の PlayDocsKeys.docsVersion でコントロールすることができます:
PlayDocsKeys.docsVersion := "2.3.1"
この機能は、play-docs-sbt-plugin が提供された 2.2.0 以前まで遡ったバージョンのドキュメントを提供したい場合に便利です。 2.1.x より前の古いバージョンでは、ドキュメントは jar ファイルとしてパッケージングして提供されていないので、このツールはこれらのバージョンでは動作しません。
Next: git を使う
このドキュメントの翻訳は Play チームによってメンテナンスされているものではありません。 間違いを見つけた場合、このページのソースコードを ここ で確認することができます。 ドキュメントガイドライン を読んで、お気軽にプルリクエストを送ってください。