翻訳されたサイト
このページでは、翻訳された Docusaurus v1 サイトを Docusaurus v2 に移行する方法について説明します。
i18n の違い
Docusaurus v2 の i18n は、いくつかの違いを除いて、概念的には Docusaurus v1 の i18n とよく似ています。
Crowdin と緊密に連携しているわけではなく、Git や他の SaaS を代わりに使用できます。
異なるファイルシステムパス
Docusaurus v2 では、ローカライズされたコンテンツは通常 website/i18n/[locale] にあります。
Docusaurus v2 はプラグインシステムに基づいたモジュール式であり、各プラグインは独自の翻訳を管理する責任があります。
各プラグインには、website/i18n/fr/docusaurus-plugin-content-blog のように、独自の i18n サブフォルダーがあります。
更新された翻訳 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 は、Markdown ファイルを解析するために MDX を使用しています。
MDX は Markdown ファイルを React コンポーネントにコンパイルしますが、Docusaurus v1 パーサーよりも厳密であり、一部の不適切なコンテンツをレンダリングするのではなく、エラーが発生するとビルドが失敗します。
また、HTML 要素は JSX 要素に置き換える必要があります。
これは i18n にとって特に重要です。Crowdin での翻訳が不適切で、無効なマークアップを使用している場合、翻訳された v2 サイトのビルドが失敗する可能性があるため、エラーを修正するために翻訳のクリーンアップが必要になる場合があります。
移行戦略
このセクションでは、v2 に移行した後も既存の v1 の翻訳を維持する方法を理解するのに役立ちます。
Crowdin を使用して Docusaurus v1 サイトを移行するための複数の可能な戦略があり、トレードオフが異なります。
このドキュメントは、移行を支援するための最善の努力です。より良い方法を見つけた場合は、改善にご協力ください。
まず最初に、次のことをお勧めします。
- 翻訳なしで v1 Docusaurus サイトを v2 に移行する
- Docusaurus v2 の新しい i18n システムに慣れる
- 新しい未翻訳の Crowdin プロジェクトと Crowdin チュートリアルを使用して、v2 サイトで Crowdin を機能させる
Crowdin と Docusaurus v2 i18n の両方を理解せずに移行しようとしないでください。
新しい Crowdin プロジェクトを作成する
本番環境で v1 サイトが壊れるリスクを回避するために、可能な戦略の 1 つは、元の v1 Crowdin プロジェクトを複製することです。
この戦略は、Jest ウェブサイトのアップグレードに使用されました。
残念ながら、Crowdin には「プロジェクトの複製/クローン」機能がないため、複雑になります。
- 元のプロジェクトの翻訳メモリを
.tmx形式でダウンロードします (https://crowdin.com/project/<ORIGINAL_PROJECT>/settings#tm>View Records) - 翻訳メモリを新しいプロジェクトにアップロードします (
https://crowdin.com/project/<NEW_PROJECT>/settings#tm>View Records) - i18n ドキュメントに従って、Docusaurus v2 用に
crowdin.ymlを再構成します。 - Crowdin CLI を使用して、Docusaurus v2 のソースファイルを新しいプロジェクトにアップロードします。
idやslugなどの機密性の高い文字列を Crowdin で「非表示の文字列」としてマークします。- 「翻訳」タブで、「事前翻訳 > TM 経由」をクリックします (
https://crowdin.com/project/<NEW_PROJECT>/settings#translations) - まず「100% 一致」（「完全」よりも多くのコンテンツが翻訳されます）を試して、ソースを事前翻訳します。
- Crowdin の翻訳をローカルにダウンロードします。
- サイトを実行/ビルドしてみて、エラーがないか確認します。
初回試行でエラーが発生する可能性があります。事前翻訳は、翻訳すべきではないもの (フロントマター、訓戒、コードブロックなど) を翻訳しようとする可能性があり、翻訳された MD ファイルは MDX パーサーに対して無効である可能性があります。
サイトがビルドされるまで、すべてのエラーを修正する必要があります。翻訳された MD ファイルをローカルで変更し、docusaurus build --locale fr を使用して、一度に 1 つのロケールでサイトを修正することでそれを行うことができます。
これらのエラーを修正するために記述できる最終的なガイドはありませんが、一般的なエラーの原因は次のとおりです。
- Crowdin で「非表示の文字列」としてマークする文字列が十分ではなく、事前翻訳がこれらの文字列を翻訳しようとする。
- 不適切な v1 翻訳があるため、v2 で無効なマークアップが発生する: 翻訳内の不適切な HTML 要素と閉じられていないタグ
- JSX 要素の代わりに HTML 要素を使用するなど、MDX パーサーによって拒否されるもの (MDX プレイグラウンドをデバッグに使用します)
この事前翻訳プロセスを繰り返して、最終的には「完全」オプションを試し、一部の言語/ファイルのみに事前翻訳を制限することもできます。
問題のある Markdown 要素の周りに mdx-code-block を使用します。Crowdin はコードブロックを使用すると問題を少なくすることができます。
古いプロジェクトで翻訳されていた一部のものが、新しいプロジェクトで未翻訳になっていることに気付くでしょう。
Crowdin Markdown パーサーは常に進化しており、各 Crowdin プロジェクトには異なるパーサーバージョンがあるため、事前翻訳がすべての文字列を事前翻訳できない可能性があります。
このパーサーバージョンはドキュメント化されていません。プロジェクトのパーサーバージョンを知り、特定のバージョンを修正するには、Crowdin サポートに問い合わせる必要があります。
2 つの Crowdin プロジェクト間で同じ CLI バージョンとパーサーバージョンを使用すると、より良い結果が得られる可能性があります。
Crowdin には「翻訳をアップロード」機能がありますが、私たちの経験では、Markdown であまり良い結果は得られません。
既存の Crowdin プロジェクトを使用する
もし、既存のCrowdinプロジェクトの変更を気にせず、混乱させるリスクを冒してもよいのであれば、Crowdinのブランチシステムを利用できる可能性があります。
このワークフローは実際にはテストされていません。どれほど優れているかについて、ぜひご報告ください。
この方法であれば、新しいCrowdinプロジェクトを作成したり、翻訳メモリを転送したり、事前翻訳を適用したり、事前翻訳のエラーを修正したりする必要はありません。
Docusaurus v2用のCrowdinブランチを作成し、そこにv2のソースをアップロードし、準備が整ったらCrowdinブランチをメインにマージできます。
Crowdinの代わりにGitを使用する
Crowdinから移行して、代わりに翻訳ファイルをGitに追加することができます。
Crowdin CLIを使用してv1の翻訳済ファイルをダウンロードし、これらの翻訳済ファイルをDocusaurus v2の正しいファイルシステムの位置に配置します。