§翻譯 Play 文件

Play 2.3+ 提供基礎架構，協助文件翻譯人員翻譯 Play 文件並保持最新狀態。

如文件指南中所述，Play 的文件以標記格式撰寫，並將程式碼範例擷取到外部檔案中。Play 允許翻譯文件中的標記元件，同時允許將英文文件的原始程式碼範例包含在翻譯文件中。這有助於翻譯人員維持翻譯品質 - 程式碼範例會作為 Play 核心專案的一部分保持最新狀態，而翻譯後的說明則必須手動維護。

此外，Play 還提供驗證翻譯文件完整性的功能。這包括驗證翻譯中的所有內部連結，包括連結到程式碼片段的連結。

§先決條件

您需要安裝sbt。另外，取得 Play 儲存庫的複製版本，並檢出您要翻譯的分支，這樣您就有東西可以開始複製。

如果您要翻譯未發布版本的 Play 文件，則您需要先在您的機器上建置該版本的 Play，並在本地發布。這可以透過在 Play 專案的 framework 目錄中執行以下指令來完成：

sbt publishLocal

§設定翻譯

使用下列結構建立新的 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

現在在您的瀏覽器中開啟 https://127.0.0.1:9000/。您應該可以看到預設的 Play 文件。現在可以翻譯您的第一個頁面了。

將 Play 儲存庫中的標記頁面複製到您的專案。請務必確認您的專案中的目錄結構與 Play 中的目錄相符，這樣可以確保程式碼範例正常運作。

例如，如果您選擇從 manual/scalaGuide/main/http/ScalaActions.md 開始，則您需要確認它在您的專案中位於 manual/scalaGuide/main/http/ScalaActions.md。

注意：您可能會想先將整個 Play 手冊複製到您的專案中。如果您這麼做，請務必只複製標記檔案，不要複製程式碼範例。如果您複製程式碼範例，它們會覆寫 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 儲存庫需要採用非常特定的格式。目前的 main 分支是 Play 最新開發版本的說明文件。Play 的穩定版本說明文件必須在 2.3.x 等分支中。特定於特定 Play 版本的說明文件將從具有該名稱的儲存庫標籤提供，例如 2.3.1。

一旦 Play 團隊將 playframework.com 設定為提供你的翻譯，推送到你的 GitHub 儲存庫的任何變更都會在約 10 分鐘內被接收，因為 playframework.com 每 10 分鐘對其使用的所有儲存庫執行一次 git fetch。

§指定說明文件版本

預設情況下，play-docs-sbt-plugin 使用與其相同的 Play 文件範例程式碼版本和後備標記檔案，因此，如果您在 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

在此文件找到錯誤？此頁面的原始程式碼可以在這裡找到。在閱讀文件指南後，請隨時提交拉取請求。有問題或建議要分享？前往我們的社群論壇與社群展開對話。