Docusaurus 整合
將 init -t ui-docusaurus 和 docsOutput.style: "docusaurus" 用於 Docusaurus 文件網站。預設會使用 docs[] 區塊和 docusaurusCatalogDir,以便 translate-docs 可以透過一個指令翻譯頁面 Markdown 和 Docusaurus Shell JSON。
另請參閱文件、可執行的 examples/docusaurus-docs 示範,以及 examples/nextjs-app,以了解結合了 Next.js 應用程式、巢狀 Docusaurus 文件、扁平 README 與 SVG 資產的範例。
快速開始
ai-i18n-tools init -t ui-docusaurus -P openai
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths, docusaurusCatalogDir)
pnpm run i18n:sync # or: ai-i18n-tools sync
cd docs-site && pnpm build # or: cd examples/docusaurus-docs && pnpm build當您翻譯文件頁面和網站外殼字串(導覽列、頁尾、主題字串)時,請啟用 features.translateDocs 並設定 docs[].docusaurusCatalogDir。在您的 Docusaurus 專案中執行 docusaurus write-translations,當您升級 @docusaurus/* 或更改導覽列/頁尾/主題標籤時 — 然後重新執行 translate-docs 或 sync,以便將外殼 JSON 翻譯到每個語系資料夾中。
頁面版面
英文 Markdown 和 MDX 位於您的 Docusaurus docs/ 資料夾下(例如 docs-site/docs/)。翻譯後的副本會寫入每個地區設定的外掛程式內容樹中:
docs-site/docs/getting-started.md
→ docs-site/i18n/de/docusaurus-plugin-content-docs/current/getting-started.md
docs-site/docs/guide/quick-start.md
→ docs-site/i18n/fr/docusaurus-plugin-content-docs/current/guide/quick-start.md設定一個 docs[] 區塊:
{
"contentPaths": ["docs-site/docs/"],
"outputDir": "docs-site/i18n",
"docusaurusCatalogDir": "docs-site/i18n/en",
"addFrontmatter": true,
"docsOutput": {
"style": "docusaurus",
"docsRoot": "docs-site/docs"
}
}將 contentPaths 指向以 sourceLocale 編寫的 .md / .mdx 檔案與目錄。該語言可以是任何語言。將 docsRoot 設定為 Docusaurus 用作其內容根目錄的相同資料夾。將 outputDir 設定為 i18n/ 下各語系資料夾的父層。
連接 Docusaurus 國際化:讓 targetLocales 在 ai-i18n-tools.config.json 中與 docusaurus.config.js 中的 locales 陣列保持一致。每個 localeConfigs[locale].path 必須與 i18n/ 下的資料夾名稱相符(例如 path: "fr" 對於 i18n/fr/)。
在現有網站中啟用 i18n
首次設定會使用 新增 i18n 到網站或文件網站 上的提示。下方的檢查清單是相同的手動操作。
- 當 URL 路徑應與語系代碼不同時,在
docusaurus.config.js中新增i18n區塊:defaultLocale、locales及localeConfigs[locale].path。 - 執行
docusaurus write-translations以確保i18n/<defaultLocale>/存在,然後將docusaurusCatalogDir指向該資料夾並執行sync。 src/pages與src/components中的自訂 React 不是 markdown。請使用來自@docusaurus/Translate的<Translate>或translate()標記使用者可見的文案,以便write-translations能將其收集到code.json中。訊息必須是靜態字串。write-translations會寫入i18n/<locale>/code.json;設定docusaurusCatalogDir後,translate-docs會將該 JSON 與其餘的 shell 訊息目錄一併翻譯。ai-i18n-tools 不會掃描那些 JSX 樹狀結構來尋找t()。
Shell 字串 (write-translations)
Docusaurus 導覽列、頁尾、搜尋佔位符以及其他主題/外掛程式標籤不會從 Markdown 中提取。在您的 Docusaurus 專案中執行 docusaurus write-translations 以在預設地區設定資料夾(通常是 i18n/en/)下產生 JSON 目錄。然後將 docs[].docusaurusCatalogDir 指向該資料夾:
{
"features": {
"translateDocs": true
},
"docs": [
{
"description": "Docusaurus pages + shell JSON",
"contentPaths": ["docs-site/docs/"],
"outputDir": "docs-site/i18n",
"docusaurusCatalogDir": "docs-site/i18n/en",
"docsOutput": {
"style": "docusaurus",
"docsRoot": "docs-site/docs"
}
}
]
}當設定 docusaurusCatalogDir 且啟用 features.translateDocs 時,translate-docs 會翻譯兩者:
- 文件頁面 — 從
contentPaths到i18n/<locale>/docusaurus-plugin-content-docs/current/的 Markdown/MDX - Shell JSON — 從
i18n/en/到同級地區設定資料夾的導覽列、頁尾和主題/外掛程式目錄
請勿將 Docusaurus Shell JSON 放入 json[];請改用 docs[].docusaurusCatalogDir 和文件。
範例專案
examples/docusaurus-docs — 英文來源位於 docs/,提交的翻譯位於 i18n/<locale>/docusaurus-plugin-content-docs/current/,以及翻譯後的 shell JSON。在連接埠 3100 上執行 pnpm start(建置 + 服務)以使語系下拉選單正常運作;使用 pnpm dev 進行僅限英文的熱重載。
如需相同儲存庫佈局中的 UI 字串、SVG 翻譯與扁平 README,請參閱 examples/nextjs-app(連接埠 3040 上的巢狀 docs-site/)。