i18n - はじめに

Docusaurus ウェブサイトは、国際化（i18n）サポートにより簡単に翻訳できます。

目標

Docusaurus の i18n サポートの背後にある設計上の決定事項を理解することが重要です。

より詳しい情報については、最初のRFCとPRをご覧ください。

i18n の目標

Docusaurus の i18n システムの目標は以下のとおりです。

• シンプル: 翻訳済みのファイルを正しいファイルシステムの場所に配置するだけです。
• 柔軟な翻訳ワークフロー: Git（モノレポ、フォーク、またはサブモジュール）、SaaS ソフトウェア、FTP を使用します。
• 柔軟なデプロイオプション: シングルドメイン、マルチドメイン、またはハイブリッド。
• モジュール式: プラグインの作者が i18n サポートを提供できるようにします。
• 低オーバーヘッドのランタイム: ドキュメントはほとんど静的であり、重い JS ライブラリやポリフィルは必要ありません。
• スケーラブルなビルド時間: ローカライズされたサイトを個別にビルドおよびデプロイできます。
• アセットのローカライズ: サイトの画像には、翻訳する必要があるテキストが含まれている場合があります。
• カップリングなし: SaaS を使用する必要はありませんが、統合は可能です。
• Crowdin との簡単な使用: 多くの Docusaurus v1 サイトは Crowdin を使用しており、v2 に移行できる必要があります。
• 優れた SEO デフォルト値: hreflangなどの便利な SEO ヘッダーを設定します。
• RTL サポート: 右から左に読むロケール（アラビア語、ヘブライ語など）がサポートされており、簡単に実装できます。
• デフォルトの翻訳: クラシックテーマのラベルは、多くの言語で翻訳されています。

i18n の非目標

サポートしていないもの

• 自動ロケール検出: 主張的で、サーバー（ホスティングプロバイダー）で実行するのが最適です。
• 翻訳 SaaS ソフトウェア: 選択した外部ツールを理解する責任があります。
• スラッグの翻訳: 技術的に複雑で、SEO 価値はほとんどありません。

翻訳ワークフロー

概要

翻訳された Docusaurus ウェブサイトを作成するためのワークフローの概要

1. 設定: docusaurus.config.jsでデフォルトのロケールと代替ロケールを宣言します。
2. 翻訳: 翻訳ファイルを正しいファイルシステムの場所に配置します。
3. デプロイ: シングルドメインまたはマルチドメイン戦略を使用してサイトをビルドおよびデプロイします。

翻訳ファイル

3種類の翻訳ファイルを使用します。

Markdown ファイル

これは、Docusaurus ウェブサイトの主なコンテンツです。

Markdown と MDX ドキュメントは、各文を個別の文字列として分割するのではなく、翻訳コンテキストを完全に保持するために、全体として翻訳されます。

JSON ファイル

JSON は、以下の翻訳に使用されます。

• React コード: src/pages のスタンドアロン React ページ、またはその他のコンポーネント。
• themeConfig を介して提供されるレイアウトラベル: ナビゲーションバー、フッター。
• プラグインオプションを介して提供されるレイアウトラベル: ドキュメントサイドバーのカテゴリラベル、ブログサイドバーのタイトルなど。

使用される JSON 形式はChrome i18nと呼ばれます。

{
  "myTranslationKey1": {
    "message": "Translated message 1",
    "description": "myTranslationKey1 is used on the homepage"
  },
  "myTranslationKey2": {
    "message": "Translated message 2",
    "description": "myTranslationKey2 is used on the FAQ page"
  }
}

2つの理由で選択されました。

• 説明属性: 翻訳者に追加のコンテキストを提供します。
• 広くサポートされている: Chrome 拡張機能、Crowdin、Transifex、Phrase、Applangaなど。

データファイル

一部のプラグインは、全体としてローカライズされた外部データファイルから読み込む場合があります。たとえば、ブログプラグインは、i18n/[locale]/docusaurus-plugin-content-blog/authors.yml の下にコピーを作成することで翻訳できる authors.yml ファイルを使用します。

翻訳ファイルの場所

翻訳ファイルは、正しいファイルシステムの場所に作成する必要があります。

各ロケールとプラグインには、独自の i18n サブフォルダーがあります。

website/i18n/[locale]/[pluginName]/...

注記

複数インスタンスのプラグインの場合、パスは website/i18n/[locale]/[pluginName]-[pluginId]/... です。

非常にシンプルな Docusaurus サイトをフランス語に翻訳すると、次のツリーになります。

website/i18n
└── fr
    ├── code.json  # Any text label present in the React code
    │              # Includes text labels from the themes' code
    ├── docusaurus-plugin-content-blog # translation data the blog plugin needs
    │   └── 2020-01-01-hello.md
    │
    ├── docusaurus-plugin-content-docs # translation data the docs plugin needs
    │   ├── current
    │   │   ├── doc1.md
    │   │   └── doc2.mdx
    │   └── current.json
    │
    └── docusaurus-theme-classic # translation data the classic theme needs
        ├── footer.json   # Text labels in your footer theme config
        └── navbar.json   # Text labels in your navbar theme config

JSON ファイルは、docusaurus write-translations CLI コマンドで初期化されます。各プラグインは対応するフォルダーの下で独自の翻訳済みコンテンツを取得し、code.json ファイルは React コードで使用されるすべてのテキストラベルを定義します。

各コンテンツプラグインまたはテーマは異なり、独自の翻訳ファイルの場所を定義します。

• ドキュメントの i18n
• ブログの i18n
• ページの i18n
• テーマの i18n