§翻译 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 docs sbt 插件，即

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

最后，build.sbt 应启用 Play docs 插件，即

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

现在在浏览器中打开 https://127.0.0.1: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 文档 sbt 插件提供了一个文档验证任务，该任务对文档运行一些简单的测试，以确保链接和代码示例引用的完整性。您可以通过运行以下命令来运行它：

sbt validateDocs

您还可以验证 Play 文档中指向外部网站的链接。这是一个单独的任务，因为它依赖于 Play 文档链接到的互联网上的许多网站，并且验证任务实际上会触发某些网站上的 DDoS 过滤器。要运行它，请运行：

sbt validateExternalLinks

§翻译报告

Play 提供的另一个非常有用的工具是翻译报告，它显示了哪些文件尚未翻译，并尝试检测问题，例如，如果翻译引入了新文件，或者如果翻译缺少代码示例。这在翻译新版本的文档时特别有用，因为代码示例的添加或删除通常是某些内容已更改的良好信号。

要查看翻译报告，请运行文档服务器（像往常一样），然后在浏览器中访问 https://127.0.0.1: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 存储库的更改将在大约 10 分钟内被拾取，因为 playframework.com 每 10 分钟对它使用的所有存储库执行一次 git fetch。

§指定文档版本

默认情况下，play-docs-sbt-plugin 使用与自身相同的 Play 文档代码示例和回退 markdown 文件版本，因此如果您在 plugins.sbt 中使用 2.4.0，当您运行文档时，您将获得 2.4.0 的文档代码示例。您可以通过在 build.sbt 中设置 PlayDocsKeys.docsVersion 来控制此版本

PlayDocsKeys.docsVersion := "2.3.1"

如果您想为 Play 早于引入 play-docs-sbt-plugin 的版本提供文档，例如 2.2.0 及更早版本，这将特别有用。对于 2.1.x 及更早版本，文档没有打包并发布为 jar 文件，因此该工具不适用于这些旧版本。

下一步： 使用 Git

发现此文档中的错误？此页面的源代码可以在此处找到。阅读完文档指南后，请随时贡献拉取请求。有疑问或建议要分享？前往我们的社区论坛与社区进行交流。