翻訳への貢献

Playground のドキュメントをあらゆる言語に翻訳できます。このページでは、Playground ドキュメントの翻訳に貢献するための包括的なガイドを提供しています。

どうすれば翻訳に貢献できますか?

他のドキュメントページへの貢献と同じワークフローを使用します。WordPress/wordpress-playground をフォークして変更内容をプルリクエストとして送信したり、GitHub UI を使用してページを直接編集したりできます。

情報

Playground Docs への貢献方法の詳細については、貢献するにはどうすればいいですか? を参照してください。

翻訳実装の詳細

情報

Docusaurus ウェブサイト (Playground Docs のエンジン) での翻訳管理の詳細については、Docusaurus Docs の国際化セクションを参照してください。

Docs サイトで利用可能な言語は、docusaurus.config.jsで定義されています。例:

i18n: {
  defaultLocale: 'en',
  path: 'i18n',
  locales: ['en', 'fr'],
  localeConfigs: {
	en: {
		label: 'English',
		path: 'en',
	},
	fr: {
		label: 'French',
		path: 'fr',
	},
  },
}

翻訳されたドキュメントページは、WordPress/wordpress-playground リポジトリにあります。

packages/docs/site/i18n/ の下には、各言語用のフォルダがあります。例えば、es (スペイン語) の場合は packages/docs/site/i18n/es フォルダがあります。

各言語フォルダの下には、docusaurus-plugin-content-docs/current フォルダがあります。例えば、es (スペイン語) の場合は、packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current フォルダがあります。

docusaurus-plugin-content-docs/current の下に、元のドキュメントと同じファイル構造 (packages/docs/site/docs の下と同じファイル構造) が複製される必要があります。

たとえば、es (スペイン語) の場合、次の翻訳ファイルが存在します: packages/docs/site/i18n/es/docusaurus-plugin-content-docs/current/main/intro.md

言語のフォルダにファイルがない場合、デフォルトの言語の元のファイルが読み込まれます。

新しい言語が追加されると (PR #1807 を参照)、packages/docs/site から npm run write-translations -- --locale <%LANGUAGE%> を実行して、特定の言語に翻訳できるメッセージを含む JSON ファイルを生成できます。

適切な i18n の docusaurus.config.js 構成と i18n の下のファイルを使用すると、プロジェクトのルートから npm run build:docs を実行すると、dist の下に各言語の特定のフォルダーが作成されます。

言語をローカルでテストする方法

既存の言語をローカルでテストするには、次の操作を実行します。

利用可能な言語のいずれかの配下のファイルを変更（翻訳）します：packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current
/packages/docs/site から、テストしたい言語のバージョンを実行します。例えば、es をテストするには、次のようにします。

npm run dev -- --locale es

言語スイッチャー - 言語を変更するための UI 要素

「言語スイッチャー」は、docusaurus (Playground Docs の背後にあるドキュメントエンジン) によって提供される UI 要素であり、ユーザーはこれを使用して特定のページの言語を変更できます。

翻訳版の可視性を高めるために、docusaurus.config.js に次の行を追加することで言語スイッチャーを表示できます。

{
  type: 'localeDropdown',
  position: 'right',
},

これにより、ヘッダーにドロップダウンが生成され、各ファイルの言語バージョンに直接アクセスできるようになります。

このドロップダウンで特定の言語を選択するのは、翻訳済みのページがかなり多い場合のみにすることを強くお勧めします。翻訳済みのページが少ない状態で選択すると、ユーザーがその言語を選択しても、どのページもその言語に翻訳されないという状況に陥ります。

言語スイッチャーで言語を公開する

言語の i18n セットアップが完了し、正しいファイル構造が i18n で利用できる場合は、すべての言語が利用可能になります。

これらの言語バージョンのドキュメントは、その言語に翻訳されたページが十分に増えるまで、言語スイッチャーでは非表示にしておく必要があります。より正確に言うと、少なくともドキュメントセクションが特定の言語に完全に翻訳され、以下のセクションも含まれている場合にのみ、言語スイッチャーでその言語を公開することをお勧めします。

言語スイッチャーに特定の言語が表示されない場合でも、翻訳されたファイルを含む PR がマージされると翻訳されたページが公開されるため、翻訳されたページを追加する作業は引き続き進行します。

fr 言語がドキュメントハブページ (クイックスタートガイド、Playground ウェブインスタンス、Playground について、ガイドなど) が完全にフランス語に翻訳された最初の言語であると仮定すると、そのブランチの docusaurus.config.js は次のようになり、npm run build:docs は fr サブサイトを適切に生成し、localeDropdown 言語スイッチャーにフランス語のみを表示します。

  {
    "i18n": {
      "defaultLocale": "en",
      "path": "i18n",
      "locales": [
        "en",
        "fr"
      ],
      "localeConfigs": {
        "en": {
          "label": "English",
          "path": "en"
        },
        "fr": {
          "label": "French",
          "path": "fr"
        }
      }
    }
  },
  {
    "type": "localeDropdown",
    "position": "right"
  }

言語スイッチャーをローカルでテストする

localeDropdown をローカルでテストしたところ、ローカルでは表示されるものの、翻訳されたページが見つからないため、期待通りに動作しないことがわかりました。しかし、本番環境では問題なく動作するようです。

任意のフォークから localeDropdown をテストし、プロジェクトのルートから実行できます。

npm run build:docs
npm run deploy:docs

これにより、フォークしたリポジトリの GitHub ページに 3 つのバージョンのドキュメントが生成されます。

https://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/
https://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/es/
https://<%GH-USER-WITH-FORK%>.github.io/wordpress-playground/fr/

したがって、localeDropdown 機能をテストするための可能なアプローチは、それをフォークされたリポジトリの GitHub Pages にデプロイすることです。

ある言語で 1 ページを翻訳するプロセス

推奨される方法は、.md ファイルを元のパス (packages/docs/site/docs) からコピーし、目的の言語パス (packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current) に貼り付けることです。packages/docs/site/docs のファイル構造を複製することが重要です。

packages/docs/site/i18n/{%LANGUAGE%}/docusaurus-plugin-content-docs/current の下のファイルを翻訳し、新しい変更を PR に反映させることができます。

PR がマージされると、そのページの翻訳バージョンが https://wordpress.github.io/wordpress-playground/{%LANGUAGE%} の下に表示されます。

どうすれば翻訳に貢献できますか?​

翻訳実装の詳細​

言語をローカルでテストする方法​

言語スイッチャー - 言語を変更するための UI 要素​

言語スイッチャーで言語を公開する​

言語スイッチャーをローカルでテストする​

ある言語で 1 ページを翻訳するプロセス​