ドキュメント

§Playドキュメントの翻訳

Play 2.3以降では、Playドキュメントの翻訳者がドキュメントを翻訳し、最新の状態に保つのを支援するインフラストラクチャが提供されています。

ドキュメントガイドラインで説明されているように、Playのドキュメントはmarkdown形式で記述され、コードサンプルは外部ファイルに抽出されます。Playでは、ドキュメントのmarkdownコンポーネントを翻訳できますが、英語のドキュメントからの元のコードサンプルを翻訳されたドキュメントに含めることができます。これにより、翻訳者は翻訳の品質を維持するのに役立ちます。コードサンプルはコアPlayプロジェクトの一部として最新の状態に保たれ、翻訳された説明は手動で維持する必要があります。

これに加えて、Playは翻訳されたドキュメントの整合性を検証する機能も提供しています。これには、翻訳内のコードスニペットへのリンクを含む、すべての内部リンクの検証が含まれます。

§前提条件

sbtをインストールする必要があります。翻訳するブランチをチェックアウトしたPlayリポジトリのクローンがあると、コピーして開始するものが手に入るので、非常に便利です。

Playドキュメントの未リリースバージョンを翻訳する場合は、まずそのバージョンのPlayをビルドし、マシンにローカルに公開する必要があります。これは、次のコマンドを実行することで実行できます

sbt publishLocal

Playプロジェクトのframeworkディレクトリで。

§翻訳の設定

次の構造で新しいsbtプロジェクトを作成します

translation-project
  |- manual
  | |- javaGuide
  | |- scalaGuide
  | |- gettingStarted
  | `- etc...
  |- project
  | |- build.properties
  | `- plugins.sbt
  `- build.sbt

build.propertiesにはsbtバージョンを含める必要があります。例：

sbt.version=1.9.6

plugins.sbtには、Playドキュメントのsbtプラグインを含める必要があります。例：

addSbtPlugin("org.playframework" % "play-docs-sbt-plugin" % "3.0.x")

最後に、build.sbtはPlayドキュメントプラグインを有効にする必要があります。例：

lazy val root = (project in file(".")).enablePlugins(PlayDocsPlugin)

これで翻訳を開始する準備ができました！

§ドキュメントの翻訳

まず、ドキュメントサーバーを起動します。ドキュメントサーバーは、作成中のドキュメントを公開し、その外観を確認できるようにします。

$ 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で最新の状態に保たれるようになります。

状況によっては、それらをオーバーライドするのが理にかなっている場合があります。これは、フェンス付きブロックを使用してコードをドキュメントに直接記述するか、プロジェクト独自のコンパイル済みコードサンプルに抽出することによって行うことができます。それを行う場合は、sbtをコンパイルするように設定する方法について、Playドキュメントのsbtビルドファイルを確認してください。

§ドキュメントの検証

Playドキュメントsbtプラグインには、ドキュメントに対していくつかの簡単なテストを実行し、リンクとコードサンプルの参照の整合性を確保するドキュメント検証タスクが用意されています。これは、次を実行することで実行できます

sbt validateDocs

Playドキュメント内の外部サイトへのリンクも検証できます。これは、Playドキュメントがリンクしているインターネット上の多くのサイトに依存しており、検証タスクが実際には一部のサイトでDDoSフィルターをトリガーするため、別のタスクです。実行するには、次を実行します

sbt validateExternalLinks

§翻訳レポート

Playによって提供されるもう1つの非常に役立つツールは、翻訳レポートです。このレポートには、翻訳されていないファイルが表示され、翻訳によって新しいファイルが導入された場合や、翻訳にコードサンプルが欠落している場合など、問題を検出しようとします。これは、ドキュメントの新しいバージョンを翻訳するときに特に役立ちます。コードサンプルの追加または削除は、何かが変更されたことを示す良いシグナルになることが多いためです。

翻訳レポートを表示するには、（通常どおり）ドキュメントサーバーを実行してから、ブラウザでhttp://localhost:9000/@reportにアクセスします。デフォルトでは、過去に生成された場合はレポートのキャッシュバージョンが提供されます。レポートを再実行するには、[レポートの再実行]リンクをクリックします。

§playframework.comへのドキュメントのデプロイ

playframework.comは、gitリポジトリからドキュメントを提供します。翻訳をplayframework.comから提供したい場合は、ドキュメントをGitHubリポジトリに配置し、Playチームに連絡してplayframework.comに追加してもらう必要があります。

gitリポジトリは非常に特定の形式である必要があります。現在のメインブランチは、Playの最新開発バージョンのドキュメント用です。Playの安定バージョンのドキュメントは、2.3.xなどのブランチにある必要があります。Playの特定のリリースに固有のドキュメントは、2.3.1などの名前の付いたリポジトリのタグから提供されます。

Playチームがplayframework.comを構成して翻訳を提供すると、GitHubリポジトリにプッシュされた変更は、playframework.comが使用するすべてのリポジトリで10分ごとにgit fetchを実行するため、約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が導入される前のPlayのバージョン（2.2.0まで）のドキュメントを提供したい場合に特に役立ちます。2.1.x以前の場合、ドキュメントはjarファイルとしてパッケージ化および公開されなかったため、ツールはこれらの古いバージョンでは機能しません。

次へ：gitの操作

このドキュメントにエラーを見つけましたか？このページのソースコードはこちらにあります。ドキュメントガイドラインを読んだら、お気軽にプルリクエストを投稿してください。質問やアドバイスがありますか？コミュニティフォーラムにアクセスして、コミュニティとの会話を始めましょう。