静的コンテンツをローカライズする
翻訳したドキュメントやカタログを、サイトやレンダラーが読み込むファイルに対応付け、構造、リンク、実際に配信される内容を検証します。
サイトのソースツリーでは、記事がすでにルート、メタデータ、ナビゲーション、レンダラーと結び付いています。その仕組みで読み込める場所に、翻訳ファイルを追加しましょう。まず目指すのは、リンクが正しく機能し、ソースと同じコード例を備えた翻訳先言語のページを、本来のルートで完全な形で表示することです。
読み込むシステムごとにファイルを整理する #
長文ドキュメント、構造化カタログ、専用リソースを分けて整理します。Markdown、MDX、Markdocにはレンダラーとスキーマが、JSON、YAML、TypeScript、PHPのカタログにはローダーが必要です。POとXLIFFは、それぞれ固有のメッセージシステムと連携します。SRTは、時間情報を扱うメディアのワークフローに属します。
各グループから代表的なソースを一つ選び、出力先のパスと、そのファイルを読み込むローダーを特定します。生成される翻訳先ファイルは、ソースのパターンに一致しない場所に配置してください。ドキュメントのID、URL、コード例、カタログのキー、値によって動作を制御するコンポーネント属性は、そのまま保持します。
形式を参照し、実際に使用するハンドラーを選びます。通常のYAMLは、ロケールをルートキーに持つYAMLやOpenAPIのYAMLとは異なります。.xmlだけでは、Androidリソースとして自動識別されません。拡張子が同じでも、ハンドラーがドキュメントの構造に対応しているとは限りません。
サイトのディレクトリ規則に合わせる #
次の構成上の項目を、プロジェクトのローダーに照らして確認してください。
| サイト | 翻訳前に確認すること |
|---|---|
| Docusaurus | どのソースドキュメントがi18n/<locale>/docusaurus-plugin-content-docs/current/配下のファイルになり、どのバージョン別ドキュメントやテーマ文字列が別の入力になるか。 |
| Nextra | 導入済みの構成が読み込むのは、ロケール別のページ、辞書、それとも別のコンテンツツリーか。入力ごとに個別に対応付けます。 |
| Hugo | content/<locale>/配下のどのファイルが同じコンテンツの翻訳として識別され、言語間のリンクがどのように解決されるか。 |
| Astro | ロケール別のどのコンテンツコレクションと画面表示用の辞書が、各ルートで使われるか。 |
| VitePress | どのロケールディレクトリのプレフィックスとナビゲーション設定が、翻訳ページの生成に使われるか。 |
| MkDocs | 導入済みのプロジェクトで、どの国際化プラグインとロケール別のドキュメント構成を使用しているか。 |
ソースドキュメントをdocs/配下に置くDocusaurusの例では、プロジェクトのルートでCLIをインストールし、リンクします。
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link.lingo/config.json内の組織IDとローカライゼーションエンジンIDは、そのまま保持します。これらのソースパスにはロケールが含まれていないため、ファイルのエントリを、出力先を明示するテンプレートに置き換えます。
{
"pattern": "docs/**/*.md",
"sourceRoot": "docs",
"targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}docs/setup/install.mdでは[path]がsetup/install.mdに変わるため、スペイン語の出力先はi18n/es/docusaurus-plugin-content-docs/current/setup/install.mdになります。導入済みのプラグインとそのバージョンが、このディレクトリを読み込むことを確認してください。テンプレートの検証と競合のルールについては、設定を参照してください。
読者に表示する項目を選んで翻訳する #
Markdownでは、タイトルや説明など、読者の目に触れるフロントマターの項目を選択します。識別情報や公開に関するメタデータは変更しません。MDXとMarkdocでは、コールアウトのタイトルなど、読者向けのコンポーネントプロパティも特定します。動作を制御するプロパティやコンポーネント名は、アプリケーションのスキーマで管理するものです。
Markdown系のファイルをすべて同じように扱えると考えず、適切なハンドラーを使用してください。.mdとして保存されたMarkdocドキュメントをMarkdocとして処理するには、形式をmarkdocと明示する必要があります。選択と再構成の制限については、Markdown、MDX、Markdocを確認してください。コードフェンスは、実行して検証できる材料として保持します。コマンドは変更せず、その前後の説明を翻訳してください。
不足しているファイルの補完を実行します。
lingo push --backfill-missing --wait完了したらサイトをビルドし、生成された翻訳先のルートを開きます。タイトル、説明、本文、カスタムコンポーネント、コードブロック、リンクを確認してください。見出しIDがテキストから生成される場合は、翻訳後のフラグメントリンクを実際にたどって確認します。URLが保持されていても、リンク先が存在するとは限りません。Next.jsでMarkdocを使うガイドでは、ロケール別に読み込む例を紹介しています。
構造化カタログの仕様を守る #
JSONと汎用YAMLの文字列値を翻訳する際は、ハンドラーのキー制御を使い、IDやエンドポイントなど、言語に関係しないデータを保護します。現行CLIのソース設定では、汎用YAMLに対してformat: "yaml"を明示的に設定してください。拡張子による推測だけでは、未設定のYAMLソースはプッシュの対象になりません。ロケールがルートキーの場合はyaml-root-keyを、OpenAPIドキュメントの構造を持つ場合はyaml-openapiを使用します。TypeScriptとPHPは、対応しているカタログ形式の範囲内で使用してください。ファイルを翻訳できるからといって、任意のソースコードを安全に評価できるわけではありません。
POでは、メッセージの識別情報、コンテキスト、複数形の構造、利用先で必要なコンパイル手順を維持します。XLIFFでは、対応する仕様のソースと翻訳先、およびプレースホルダーの構造を保持します。出力ファイルの存在を確かめるだけでなく、実際に読み込むシステムでインポートまたはビルドを検証してください。
アプリストアの説明文など、プレーンテキストの.txtファイルは、元の行構成を保ちながら行ごとに翻訳されます。metadata/en/*.txtのようにファイルパターンに.txtを含めるか、"format": "txt"を設定してください。docs/en/**/*のような広範なパターンでは、これらのファイルは選択されません。詳しくはプレーンテキストを参照してください。ロケールごとに列を持つCSVテーブルは、同じファイル内で翻訳されます。CSVの説明に従って、パターンに.csvを含めるか、"format": "csv"を設定してください。現在のCLIでは、ロケールごとに分かれたCSVファイル、WebVTT、Javaの.propertiesを、設定可能な形式として指定することはできません。CLI v0の形式リファレンスは、これらの旧ワークフローを導入済みのユーザー向けです。記載されているコマンドや設定は、そのバージョンに固有のものです。これらのリソースを気づかないうちに除外してしまわないよう、移行リファレンスを参照し、サポートされている移行方法を選んでください。
メディアを再生して字幕を確認する #
SRTでは、字幕キューのテキストを翻訳し、キューの番号とタイミングをソースと比較します。代表的なシーンを翻訳先の字幕付きで再生してください。実際のプレーヤーで、読み切れる長さか、改行は適切か、話者の文脈や書式タグに問題がないかを確認します。タイムスタンプが保持されていても、翻訳された字幕を表示時間内に読み切れるとは限りません。ファイルの仕様についてはSubRipを参照してください。どちらも字幕形式だからといって、WebVTTで代用しないでください。
検証済みの配信経路を基に規模を広げる #
設定、ソース、受け入れ済みの翻訳先ファイル、CLIのLockfileをまとめて管理します。段落を変更したら、通常の差分処理にlingo push --waitを使い、翻訳先の該当段落と未変更のセクションを比較します。以前のソースは、その翻訳先と対にして保持してください。ドキュメントの構造を組み替えると、再利用の判断が曖昧になることがあります。位置ベースのパターンでは、対象範囲を絞った処理計画の扱いが異なります。広範囲を再翻訳する前に見積もりワークフローを使い、見積もりは確定価格ではなく、計画のための情報として扱ってください。
翻訳先にローカルで加えた修正を、内容の食い違いによる上書きから保護する必要がある場合は、--waitを付けずに送信し、取得前にlingo pull --dry-runを確認します。完了を待って直接書き戻す方式には、この確認段階がありません。レビュー済みの翻訳を保持するの手順に従ってください。
一つのグループを正しくビルドできたら、GitHub Appまたは継続的インテグレーションのレシピを選びます。そのサイクルでも、サイトのビルド、スキーマ検証、リンクチェック、コンテンツのレビューを続けてください。lingo checkだけでは、ドキュメントの完全性は確認できません。更新のたびに、読める状態の翻訳先ページと、チームが次の変更に使えるソースのリビジョンを残しましょう。