已翻譯網站
此頁面說明如何將已翻譯的 Docusaurus v1 網站遷移至 Docusaurus v2。
i18n 差異
Docusaurus v2 i18n 在概念上與 Docusaurus v1 i18n 相當類似，但有少數差異。
它與 Crowdin 的連結性並不那麼強，您可以改用 Git 或其他 SaaS。
檔案系統路徑不同
在 Docusaurus v2，區域化內容通常在 website/i18n/[locale] 中。
Docusaurus v2 是基於外掛系統的模組化，各外掛負責管理自己的文字翻譯。
各外掛有自己的 i18n 子資料夾，例如：website/i18n/fr/docusaurus-plugin-content-blog
已更新的翻譯 API
使用 Docusaurus v1 時，你可以使用 <translate> 來翻譯你的頁面。
const translate = require('../../server/translate.js').translate;
<h2>
<translate desc="the header description">
This header will be translated
</translate>
</h2>;
在 Docusaurus v2 中，你可以使用 <Translate> 來翻譯你的頁面。
import Translate from '@docusaurus/Translate';
<h2>
<Translate id="header.translation.id" description="the header description">
This header will be translated
</Translate>
</h2>;
write-translations CLI 仍然適用於從你的程式碼中提取翻譯。
程式碼翻譯現在使用 Chrome i18n JSON 格式，新增至 i18n/[locale]/code.json 中。
更嚴格的 Markdown 解析器
Docusaurus v2 使用 MDX 來解析 Markdown 檔案。
MDX 會將 Markdown 檔案編譯至 React 組件，比 Docusaurus v1 解析器嚴格，並會在發生錯誤時導致你的建置失敗，而不是渲染一些錯誤的內容。
此外，HTML 元素必須使用 JSX 元素替換。
這對國際化來說特別重要，因為如果你的翻譯在 Crowdin 上不佳，且使用無效的標記，你的 v2 翻譯網站可能會無法建置：你可能需要清理一些翻譯，以修正錯誤。
移轉策略
本節將幫助你找出如何在移轉到 v2 後保留現有的 v1 翻譯。
有多種可能的策略，可以使用 Crowdin 來移轉 Docusaurus v1 站台，各有利弊。
本文件盡力幫助你移轉，如果你找到更好的方法，請幫助我們改進它！
首先，我們建議
- 在不使用翻譯的情況下，將你的 v1 Docusaurus 站台移轉到 v2
- 熟悉 Docusaurus v2 新的國際化系統 以及
- 讓 Crowdin 在你的 v2 站台運作，使用新的未翻譯 Crowdin 專案及 Crowdin 教學
在不了解 Crowdin 和 Docusaurus v2 i18n 的情況下，請勿嘗試遷移。
建立一個新的 Crowdin 專案
為避免發生讓您的 v1 網站中斷運作的風險，一種可行的策略是複製原始的 v1 Crowdin 專案。
此策略用於升級 Jest 網站。
很遺憾，Crowdin 沒有提供「複製/複製專案」功能，這使事情變得複雜。
- 以
.tmx格式下載原始專案的翻譯記憶體（https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm>查看記錄） - 將翻譯記憶體上傳到新的專案（
https://crowdin.com/project/<NEW_PROJECT>/settings#tm>查看記錄） - 根據 i18n 文件重新配置 Docusaurus v2 的
crowdin.yml - 透過 Crowdin CLI 將 Docusaurus v2 原始檔上傳到新的專案
- 在 Crowdin 上將
id或slug等敏感字串標示為「隱藏字串」 - 在「翻譯」標籤中，按一下「預先翻譯 > 透過 TM」（
https://crowdin.com/project/<NEW_PROJECT>/settings#translations） - 先嘗試「100% 匹配」（會翻譯比「完美」更多內容），並預先翻譯您的原始檔
- 在本地下載 Crowdin 翻譯
- 嘗試執行/建立您的網站並查看是否有任何錯誤
您很可能會在第一次嘗試時遇到錯誤：預先翻譯可能會嘗試翻譯不應該翻譯的內容（設定檔、警告、程式碼區塊等），而翻譯後的 MD 檔案可能會對 MDX 解析器無效。
您必須修復所有錯誤，才能建立您的網站。您可以透過修改本機翻譯的 MD 檔案來做到這一點，並使用 docusaurus build --locale fr 一次修復一個語言環境的網站。
我們無法撰寫最終指南來修復這些錯誤，但常見的錯誤是
- 在 Crowdin 中未將足夠的字串標示為「隱藏字串」，導致預先翻譯嘗試翻譯這些字串。
- 有不良 v1 翻譯，導致 v2 中標記無效：翻譯內部不良的 HTML 元素和未關閉的標籤
- 任何被 MDX 解析器拒絕的，例如使用 HTML 元素代替 JSX 元素（使用 MDX Playground 進行除錯）
您可能需要重複此預先翻譯程序，最終嘗試「完美」選項並僅限預先翻譯某些語言/檔案。
在有問題的標記元素附近使用 mdx-code-block：Crowdin 不太可能將事情搞亂程式碼區塊。
您可能會注意到，有些內容已經在您的舊專案中翻譯，但在您的新專案中現在未翻譯。
Crowdin Markdown 解析器在演變，每個 Crowdin 專案都有不同的解析器版本，這可能導致預先翻譯無法預先翻譯所有字串。
此解析器版本未記錄，您必須向 Crowdin 支援部門詢問您的專案的解析器版本並修復特定版本。
在 2 個 Crowdin 專案中使用相同的 CLI 版本和解析器版本可能會產生更好的結果。
Crowdin 有一個「上傳翻譯」功能，但根據我們的經驗，它對 Markdown 沒有很好的效果
使用現有的 Crowdin 專案
如果您不介意修改現有的 Crowdin 專案並冒著弄亂的風險，則可以使用 Crowdin 分支系統。
此工作流程尚未在實際中進行測試，請告訴我們它有多好。
這樣，您就不需要建立新的 Crowdin 專案、傳輸翻譯記憶體、套用預先翻譯並嘗試修復預先翻譯錯誤。
您可以為 Docusaurus v2 建立 Crowdin 分支，在那裡您可以上傳 v2 來源，並在準備好後合併 Crowdin 分支到主分支。
使用 Git 而不是 Crowdin
可以從 Crowdin 中遷移，並將翻譯檔案新增到 Git 中。
使用 Crowdin CLI 下載 v1 翻譯的檔案，並將這些翻譯的檔案放置在正確的 Docusaurus v2 檔案系統位置。