メッセージカタログの抽出と読み込み
ソースメッセージを抽出し、翻訳済みのJSONCファイルを取得して、対応するソースメタデータから実行時マップを構築します。
コンポーネントには、ソースメッセージとそのコンテキストが含まれます。抽出処理では、それらの呼び出しを翻訳可能なファイルにまとめます。読み込み処理では、翻訳済みの値をコンポーネントのキーに対応付けます。このレシピでは、最初のあいさつを例に、このファイルベースのワークフローを通して、プロバイダーに必要なMessagesマップを生成します。
ソースを抽出する #
アプリケーションにCLIとローダーの依存パッケージをインストールします。
npm install --save-dev @lingo.dev/cli@latest
npm install @lingo.dev/spec@1.17.1 jsonc-parser
npx lingo extract --src src --source-locale en抽出はローカルで実行され、APIキーは不要です。既定ではlocales/en.jsoncとlingo.d.tsが書き出されます。明示的に指定した--outフラグと--typesフラグは、設定済みのi18n.messagesPathとi18n.typesPathより優先され、これらの設定値は既定値より優先されます。srcの外に呼び出しがあるPagesアプリケーションでは、--src pagesなど、実際に使用しているディレクトリを指定します。
あいさつのエントリを確認します。値には英語のテンプレート全体が入り、キーはソースとコンテキストから生成されます。直前のコメントには、意味を示す@context、ソース内の位置を示す@src、以前に抽出されたエントリが使われなくなったことを示す@orphanが記録されます。翻訳をリクエストする前に、これらの変更をレビューしてください。
選択したカタログを翻訳する #
Lingo.devが未設定のアプリケーションでは、このファイルと翻訳先のスペイン語を指定して初期化し、認証を行ってローカライゼーションエンジンを関連付けます。
npx lingo init --source en --targets es --files 'locales/en.jsonc' --yes
npx lingo login
npx lingo link有効化されたローカライゼーションエンジンへのアクセスと、アカウントの十分な利用可能枠が必要です。無人実行用の認証情報については、CLI認証を参照してください。
.lingo/config.jsonがすでに存在する場合は、その関連付けと他のファイルエントリを維持してください。locales/en.jsoncを選択するエントリを追加または更新し、プロジェクトのソースロケールがenであることを確認します。既存のベースラインがある場合は、npx lingo push --waitで既存の翻訳先ロケールの通常更新を完了し、レビューが必要な状態や失敗を解消して、取得した変更を確認してから、targetLocalesにesを追加してください。その後のバックフィルが終わるまで、ソースのリビジョンは固定してください。この手順の順序については、言語を追加するを参照してください。設定の編集にinit --forceは使用しないでください。ファイルエントリが再構築され、詳細オプションが失われる可能性があります。設定の構造全体については、設定で説明しています。
新規プロジェクトの場合、または既存プロジェクトで上記の準備が完了したら、不足している翻訳先ファイルをリクエストし、取得が完了するまで待ちます。このコマンドの待機中は、翻訳先ファイルを変更しないでください。ダウンロード処理によってローカルの編集内容が上書きされる可能性があります。
npx lingo push --backfill-missing --wait実行が完了したら、locales/es.jsoncを確認します。出力を完成とみなす前に、報告されたレビューが必要な状態や失敗を解消してください。その後ソースを変更した場合は、再度抽出し、npx lingo push --waitを使用します。バックフィルは不足しているファイルを補うためのもので、既存の翻訳先ファイルの通常更新には使用しません。
翻訳先のリビジョンに対応するソースメタデータを保持する #
一般的なJSONC翻訳ワークフローでは、ソースの@orphanマークは翻訳先にも保持されますが、@contextと@srcのコメントは削除されます。翻訳先ファイルだけでは、メッセージがどのページに属していたかをローダーが判別できません。
翻訳先と同じリビジョンから抽出したソースファイルを保持してください。そのソースから有効なエントリを選び、キーを使って翻訳先の翻訳済みの値と結合します。これにより、削除されたメッセージを除外しつつ、ソースのルートに基づく選択も可能になります。翻訳先にないキーは追加されないため、実行時にソースへのフォールバックが機能します。
未加工のカタログを解析する #
アプリケーション側で管理する次のローダーを使って、src/catalog.tsを作成します。
import { parse, type ParseError } from "jsonc-parser";
import { getActiveEntries, readLocaleFile, type LocaleEntry } from "@lingo.dev/spec";
import type { Messages } from "@lingo.dev/react";
function readStringCatalog(raw: string) {
const errors: ParseError[] = [];
const value: unknown = parse(raw, errors, { allowTrailingComma: true });
if (
errors.length > 0 ||
value === null ||
typeof value !== "object" ||
Array.isArray(value) ||
Object.values(value).some((entry) => typeof entry !== "string")
) {
throw new Error("Expected a flat JSONC object with string values");
}
return readLocaleFile(raw);
}
export function loadMatchedMessages(
sourceJsonc: string,
targetJsonc: string,
include: (entry: LocaleEntry) => boolean = () => true,
): Messages {
const active = getActiveEntries(readStringCatalog(sourceJsonc).entries);
const target = new Map(readStringCatalog(targetJsonc).entries.map((entry) => [entry.key, entry.value]));
return Object.fromEntries(
active.filter(include).flatMap((entry) => {
const value = target.get(entry.key);
return value === undefined ? [] : [[entry.key, value]];
}),
);
}readLocaleFileはJSONCの構文とメタデータを解析しますが、実行時のデータ構造を検証するものではありません。宣言されたエントリ型にかかわらず、配列や文字列以外の値も受け入れ、ルートがプリミティブ値またはヌル値の場合はエントリを返しません。上記の最初の関数は、値がレンダラーに渡される前に、これらのデータ構造を拒否します。どちらの関数もローカルで動作し、入出力は行いません。
Viteアプリケーションでは、プロバイダーにデータを渡すモジュールで、ファイルを未加工のテキストとして読み込みます。
import source from "../locales/en.jsonc?raw";
import target from "../locales/es.jsonc?raw";
import { loadMatchedMessages } from "./catalog";
export const spanishMessages = loadMatchedMessages(source, target);ここでは、モジュールがsrcの直下にあり、Viteのクライアント型が含まれていることを前提としています。locale="es"で、spanishMessagesをmessagesとして渡します。これで、あいさつには取得したスペイン語のテンプレートが使われ、引き続き{name}がAnaに置き換えられるはずです。実際の文言を確認し、エントリが欠けている場合もテストしてください。ファイルの読み込みと、翻訳の言語品質の評価は別の作業です。
ルートに必要なソースエントリだけを選択する #
省略可能なinclude述語は、結合前に有効なソースエントリに対して実行されます。ページローダーでは、entry.metadata.srcを使って、そのページ自身の呼び出しと共有コンポーネントを含められます。この選択は、メタデータが残っているソース側で行ってください。デプロイ時にはソースと翻訳先を一緒に保持し、ルートに応じた選択に別のリビジョンのキーが使われないようにします。
Next Pagesのレシピには、ルート述語の完全な実装が用意されています。TanStackのレシピでは、リクエスト用カタログにこのローダーを使用しています。それぞれの組み込みローダーはメタデータ付きのファイルを絞り込めますが、どちらもコメントのない翻訳先ファイルとソースメタデータを自動で結合することはありません。
仕様ヘルパーのリファレンス #
| エクスポート | 動作仕様 |
|---|---|
readLocaleFile(content): LocaleFile | 末尾のカンマを含むJSONCと、直前のメタデータブロックコメントを解析します。構文エラーがある場合は例外をスローします。 |
getActiveEntries(entries): LocaleEntry[] | metadata.orphanが真と評価されないエントリを保持します。 |
LocaleFile | { entries: LocaleEntry[] }。 |
LocaleEntry | { key: string; value: string; metadata: EntryMetadata }。 |
EntryMetadata | context、src、orphanはいずれも省略可能です。 |
computeKey(source, context?) | ソースとコンテキストを正規化した共通の識別情報で、Reactからもエクスポートされます。 |
buildIcuPlural(forms) | 既知の基数カテゴリを正規の順序で出力します。 |
buildIcuSelect(forms) | キーを並べ替えて選択肢を出力します。 |
ICUビルダーは文字列のレコードを受け取ります。Reactの複数形と選択の型では、必須のother形式が追加されます。生成される実行時カタログは単純なMessagesマップであり、LocaleFileではありません。
既存のキー付きリソース、ドキュメント、静的なTypeScriptのロケールモジュールでは、この抽出レシピではなく、それぞれ専用の形式ハンドラーを使用します。サンプルプロジェクトでは、それらの構成をReactアプリケーションと併せて紹介しています。