Skip to content

Docusaurus統合 ​

Docusaurus ドキュメント サイトでは、init -t ui-docusaurus と docsOutput.style: "docusaurus" を使用します。プリセットは、docs[] ブロックを docusaurusCatalogDir で作成し、translate-docs でページの Markdown と Docusaurus シェルの JSON を 1 つのコマンドで翻訳できるようにします。

Documents、実行可能な examples/docusaurus-docs デモ、およびネストされたDocusaurusドキュメント、フラットなREADME、SVGアセットを組み合わせたNext.jsアプリである examples/nextjs-app も参照してください。

クイックスタート ​

bash
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プロジェクトでdocusaurus write-translationsを実行し、その後translate-docsまたはsyncを再実行して、シェルJSONが各ロケールフォルダーに翻訳されるようにします。

ページレイアウト ​

英語のマークダウンとMDXは、Docusaurusのdocs/フォルダー(例:docs-site/docs/)の下にあります。翻訳されたコピーは、各ロケールのプラグインコンテンツツリーに書き込まれます。

text
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[] ブロックを1つ設定します:

json
{
  "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のi18nを接続します。targetLocalesをai-i18n-tools.config.jsonに、locales配列をdocusaurus.config.jsに合わせます。各localeConfigs[locale].pathは、i18n/の下にあるフォルダ名(例:path: "fr" for 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はマークダウンではありません。write-translationsがユーザー向けのコピーをcode.jsonに収集できるように、@docusaurus/Translateの<Translate>またはtranslate()でマークします。メッセージは静的文字列である必要があります。write-translationsはi18n/<locale>/code.jsonを書き込みます。docusaurusCatalogDirが設定されている場合、translate-docsはそのJSONを残りのシェルカタログと一緒に翻訳します。ai-i18n-toolsは、それらのJSXツリーでt()をスキャンしません。

シェル文字列(write-translations) ​

Docusaurusのナビバー、フッター、検索プレースホルダー、他のテーマ/プラグインラベルは、マークダウンから抽出されません。Docusaurusプロジェクトでdocusaurus write-translationsを実行して、デフォルトのロケールフォルダー(通常i18n/en/)の下にJSONカタログを生成します。次に、docs[].docusaurusCatalogDirをそのフォルダーにポイントします。

json
{
  "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/へのマークダウン/MDX
  • シェルJSON — i18n/en/から同期ロケールフォルダへのナビバー、フッター、テーマ/プラグインカタログ

DocusaurusシェルJSONをjson[]に配置しないでください。代わりに、ドキュメントでdocs[].docusaurusCatalogDirを使用します。

サンプルプロジェクト ​

examples/docusaurus-docs — docs/ に英語ソース、i18n/<locale>/docusaurus-plugin-content-docs/current/ にコミットされた翻訳、さらに翻訳されたシェルJSONがあります。ロケールドロップダウンが機能するように、ポート3100で pnpm start を実行し(ビルド + サーブ)、英語のみのホットリロードには pnpm dev を使用してください。

同じリポジトリレイアウトでのUI文字列、SVG翻訳、およびフラットなREADMEについては、examples/nextjs-app(ポート3040でのネストされた docs-site/)を参照してください。

MITライセンスの下で公開されています。