ローカライゼーション
Turian のローカライゼーションシステム(ADR 0011)は、エンジン、出荷されるゲーム、そして Studio 自体で共有されています——1つのランタイム、1つの作成フォーマット、1つの CLI。このページでは、作成 → 抽出 → 翻訳 → コンパイル → 出荷というワークフローについて説明します。
文字列に到達する2つの方法
| エントリーポイント | 用途 | キー | 作成者 |
|---|---|---|---|
tr("Open Scene…") |
UI クローム(メニュー、ボタン、HUD ラベル) | ソース文字列自体 | プログラマー、コード内で |
Locale.key("dlg.act1.intro") |
ゲームコンテンツ(ダイアログ、アイテム名、クエスト) | 明示的な安定した id | デザイナー、.strings アセット内で |
どちらも同じテーブルにコンパイルされ、同じ Locale サービスによって提供されます——唯一の違いは id の出所です。
// シンプルなテキスト
frame.tr("Open Scene…")
// コンテキストによる曖昧さ回避(同一の英語文字列だが意味が異なる)
frame.trc("door", "Open")
// 複数形(CLDR の基数ルールがアクティブな言語に応じた正しい形式を選択)
frame.trn("# file", "# files", count, &.{})
// 補間(ICU サブセットの名前付きプレースホルダー、std.fmt 指定子ではない)
frame.trArgs("Save changes to \"{title}\" before closing?", &.{
.{ .name = "title", .value = .{ .text = doc_title } },
})
// デザイナーが作成したゲームコンテンツ、id で検索
frame.trKey("dlg.act1.intro", &.{})
tr/trc/trn はメッセージを comptime パラメーターとして受け取ります——リテラルでない引数は、レビューコメントではなくコンパイルエラーになります。翻訳が見つからない場合は、生のキーではなく常に英語のソースに劣化します。key/trKey は、デバッグビルドでは ⟦the.key⟧ に、リリースでは裸のキーに劣化するため、デザイナーコンテンツの翻訳漏れが静かに見えなくなることはありません。
メッセージ構文は ICU MessageFormat のドキュメント化されたサブセットです：{name}、{count, plural, one {# file} other {# files}}(オプションの正確な値の分岐 =0 {...} 付き)、{gender, select, male {He} other {They}}。
サービスの登録
var locale = engine.Locale.init("en"); // default_locale
locale.loadTable(embedded_pt_br_strtab) catch {};
frame.services.register(engine.Locale, &locale);
実行時に言語を切り替えられます——UI は毎フレーム再レンダリングされるため、シーンの再読み込みは不要です：
locale.setLocale("pt-BR");
読み込まれたテーブルはセッション中キャッシュされ、切り替え時に解放されることはないため、すでに渡された文字列スライスは有効なままです(再取得するまでは古いロケールを表示し続けます)。
翻訳の作成
.strings ファイルが信頼できる情報源です——ロケールごとに1つの JSON ファイル：
{
"version": 1,
"locale": "pt-BR",
"units": [
{ "id": "Open Scene…", "source": "Open Scene…", "target": "Abrir Cena…", "state": "translated" }
]
}
抽出 → 翻訳 → コンパイル
# ソースツリーを走査して tr/trc/trn/trKey の呼び出し箇所を見つけ、
# .strings ファイルを書き込む(または既存の翻訳を保持しつつ更新する):
turian-cli i18n extract <src-dir> pt-BR my-project/i18n/pt-BR.strings.json
# 各ユニットの "target" を埋めてから、コンパイル済みランタイム形式にベイクする:
turian-cli i18n compile my-project/i18n/pt-BR.strings.json my-project/i18n/pt-BR.strtab
extract はいつでも安全に再実行できます：一致する id は既存の target を保持し、新しい呼び出し箇所は state: "new" で追加されます。compile は空でない target を持つユニットのみを出力します——翻訳されていない文字列は単にテーブルに含まれず、実行時に英語のソースにフォールバックするため、部分的な翻訳カバレッジが致命的なエラーになることはありません。
Studio 自体の翻訳
Studio 自身の UI は、studio/services/StudioLocale.zig(1つの Locale インスタンスに支えられた tr/trc/trn/trArgs を公開する薄いラッパー)を通じて、まったく同じ仕組みを使用します。Studio はプロジェクトではないため、そのカタログはアセットパイプラインを通さず @embedFile されます：studio/i18n/<locale>.strings.json(ソース)と studio/i18n/<locale>.strtab(コンパイル済み、埋め込み)。
UI コードを変更した後に Studio の pt-BR カタログを更新するには：
turian-cli i18n extract studio pt-BR studio/i18n/pt-BR.strings.json
# .strings.json 内の新しいユニット(state: "new")を翻訳する
turian-cli i18n compile studio/i18n/pt-BR.strings.json studio/i18n/pt-BR.strtab
言語ピッカーは Settings → UI → Language にあります。切り替えは即座に反映されます(Studio はその選択を editor.ui.language に永続化します)。
複数形
複数形カテゴリーは、アクティブな言語の CLDR 基数ルールから解決されます——one/few/many/other(アラビア語などの言語では zero/two も)——手書きの言語別条件分岐ではありません。trn/{n, plural, ...} は一般的なケースをカバーします。明示的な =0 {...} スタイルの分岐が存在する場合は、カテゴリーより優先されます。
対象外
RTL レイアウトのミラーリング、BiDi シェイピング、機械翻訳は、このシステムの対象外です。将来の RTL サポートのために、ロケールメタデータに direction フィールドが予約されています。