ローカライズシート

一つのシートに、あらゆる言語のゲームテキストを収めます: 行がキー、列がロケール です。ローカライズシートは、重要な点においてはすべて通常の SheetForge のシートです——データシートとまったく同じようにインポート、検証、エクスポート、プッシュ、ラウンドトリップされます——そして Unity Localization パッケージ(com.unity.localization)がインストールされていれば、完了したすべてのインポートが、そこからパッケージ自身の StringTable コレクション も満たします。あなたのランタイムは、シートが唯一の信頼できる情報源であり続けながら、標準の LocalizedString 参照を消費することになります。

このページが扱うのは あなたのゲームのテキスト です。製品自身の 10 言語対応 UI は別の主題であり、ローカライズを参照してください。

シートの形(`@loc`)

シートは @loc マーカー行 を持つことで、ローカライズシートになります。@overlap や @style と同様、データより上のどこにあっても構いません。各列のセルが、その列の ロケールコード を指定します:

@loc     |            | en             | ko          |       |
@name    | codeName   | en             | ko          | smart | comment
@type    | RecordId   | string?        | string?     | bool? | string?
@desc    | key        | source text    | Korean      |       |
         | ui.ok      | OK             | 확인        | false | Confirm button
         | ui.cancel  | Cancel         | 취소        |       |

RecordId のキー列が必須です——各行のキーの値(ui.ok)がローカライズキーであり、タブ名が StringTable コレクションの名前 になります: タブ一つにつきコレクション一つです。
ロケール列は文字列型の列 であり、その @loc セルがコード(en、ko、pt-BR——識別子のような形のタグであれば何でも構いません。SheetForge が検証するのはコードの綴りの形であって、そのコードが実在するかどうかではありません。大文字小文字だけが異なる二つの列は却下されます)を持ちます。string? として書くのが推奨される形です: そうすれば、未翻訳のセルはインポートエラーではなく カバレッジの欠落 になります——下記のカバレッジを参照してください。
最初のロケール列がソースロケールです。 そのテキストが、データシートの参照セルがインラインでプレビューするものであり、自動ミンティングが書き込むものです。
名前で一致する、二つの予約された任意列: smart(真偽値——そのエントリを Unity Localization の Smart String としてマークします)と comment(文字列——そのエントリのコメントメタデータへ同期されます)。これらの列が存在すれば、シートがその部分についての正規の情報源になります。存在しなければ、ブリッジは対応するテーブルのメタデータに触れずそのままにします。予約された列がロケールコードを同時に持つことはできません。
少なくとも一つのロケールコードが必要であり、一つのシートが enum シートとローカライズシートを兼ねることはできません(@enum と @loc の両方があるのは矛盾エラーで、一度だけ報告されます)。

それ以外はすべて通常のシートです: ステージングと Ctrl+Z、構造編集、@style によるグルーピング、xlsx と Google のラウンドトリップ、Push、そしてウェブアプリのすべてが、これを普通のテーブルとして扱います。変わるのは出力です: ローカライズタブは、生成されるレコードクラスも、Database ScriptableObject も、Addressables のアドレスも出力しません。 その代わりに、二つのものを供給します——キー定数とブリッジです。

データシートからテキストを参照する(`LocRef@Tab`)

データシートは、LocRef 参照列 を使ってローカライズエントリを指し示します:

@name    | codeName    | displayName
@type    | RecordId    | LocRef@Strings
@desc    | unique key  | shown in UI
         | item.sword  | item.sword.name

LocRef@Strings は、あなたがすでに知っている組み込みの参照(RecordId@Tab)とまったく同じように振る舞います:

インポート時に整合性が検証されます——Strings タブに存在しないキーは、最も近い候補の提案付きの構造化されたエラーになります。タイプミスは、実行時ではなくインポート時に失敗します。対象はローカライズシートでなければならず(そうでなければ LocRefTargetNotLocalizationSheet)、@Target を伴わない LocRef は正しい綴りの提案とともに却下されます。
完全な参照レール——検索可能なキーピッカー、キーのリネーム時の伝播(キーをリネームすると、同じバッチ内で参照しているすべてのセルが書き換えられます)、レコードキャンバス上のグラフエッジ、エクスポートされるドロップダウンルール、そして孤立検出のすべてが、エディターでもウェブアプリでも同じように機能します。
他の参照と同じように組み合わせられます——List<LocRef@Strings> と、任意形式の LocRef@Strings?(空のセルは空の参照)のどちらも機能します。
セルはキーだけでなくテキストを表示します。 LocRef セルはそのエントリのソースロケールのテキストをインラインでプレビューするため、キーだらけのシートも、依然として文として読めます。レコードキャンバスも同じです——参照行はソーステキストを添えて表示し、切り詰められた値は常にツールチップが全文を持ちます。
空のセルに入力すると、そのエントリがミンティングされます。 空の LocRef セルにソーステキストを入力すると、SheetForge は 一つのジェスチャー、一つの undo ステップ として、次のものをステージングします: 対象のローカライズシートに追加される新しいキー(レコード名とフィールド名から提案されます——後から自由にリネームでき、伝播があらゆる参照を保ったままにします)、あなたが入力したテキストをそのソースロケールの値として、そしてあなたが入力したセルの中にその参照を。両方のホストで機能します。

あなたのコードに何が現れるか

コード生成は、そのフィールドを LocRef——SheetForge のランタイムアセンブリに存在する、対象テーブルとキーを保持する素のシリアライズ可能な構造体——として出力します。これは Unity Localization パッケージがインストールされていてもいなくてもコンパイルされ、生成されたコードとベイクされた ScriptableObject がパッケージの型を含むことは決してありません。パッケージがインストールされていれば、一つの拡張メソッド呼び出しがそこへのブリッジになります:

var text = definition.displayName.ToLocalizedString(); // UnityEngine.Localization.LocalizedString

ToLocalizedString() は、パッケージが存在するときにだけ存在します(バージョン定義 SHEETFORGE_LOCALIZATION が、拡張レイヤーを有効にします——SHEETFORGE_ADDRESSABLES が使うのと同じ仕組みです)。パッケージがなくても、そのフィールドは、あなた自身が消費できる、整った形のテーブル/キーのペアのままです。

インポートが生成するもの

通常の出力に加えて、インポートはプロジェクト全体のために一つの SheetForgeLocalizationKeys.cs を書き出します——ローカライズタブごとの静的クラス(StringsKeys、……)がキーごとに一つの public const string を保持し、ゲームコードは裸の "ui.ok" の代わりに StringsKeys.ui_ok と書くことで、コンパイル時の安全性と IDE の補完を得られます。

メンバー名は、C# の識別子にサニタイズされた キーです(ASCII の英字・数字・_ 以外の文字は _ になります。衝突には決定的な数値の接尾辞が付きます)。使える定数が欲しいなら キーは ASCII のままにしてください——完全に非 ASCII なキーは、アンダースコアの羅列にサニタイズされてしまいます。
シート定義の enum ファイルと同様、この定数ファイルもプロジェクトレベルの出力であり、常に設定にある生成コードフォルダーへ書き出されます——機能と制限にある同じアセンブリの注記が当てはまります。
行を一つも持たないローカライズタブは、空のクラス を保ち続けるため、シートを空にしてもその型を参照しているコードが壊れることはありません。

Unity Localization ブリッジ

パッケージがインストールされていれば、SheetForge は ローカライズタブごとに一つの StringTable コレクション——キー、値、そしてそれらの列が存在する場合の smart/comment の情報——を維持します。

いつ実行されるか: 自動的に、インポートが完了した瞬間に——Export や Push が出口として持っているのと同じ立ち位置です——それに加えて、必要なときに実行するための 手動の再同期アクション もあります。
方向: 一方向、シート → テーブル です。シートが正規であり、テーブルは出力です。
ロケール: プロジェクト内に対応する Locale アセットがないシートのロケールは、自動的に作成され、レポートに名前が記載されます。プロジェクトにのみ存在するロケールは、触れられないまま残され、シートでカバーされていない と報告されます。
キーのリネームは、シーンの参照を生かし続けます。 Data Studio でのキーのリネームは、あらゆる参照が使うのと同じリネームの仕組みを通り、ブリッジはテーブルのエントリをその場で、内部 id を保ったままリネームします——シーンやプレハブの中の LocalizedString はその id に結び付いているため、リネームを生き延びます。正直な境界: Studio の外側で行われたリネーム——Google Sheets や Excel でシートのソースを直接編集すること——は、一つのキーを削除して別のキーを追加することと見分けがつきません。ブリッジは新しいエントリ(新しい id)を作成し、古いほうを孤児として扱います。古いエントリへのシーンの参照は、その孤児を指したままになります。キーは Studio でリネームしてください。
シートがモデル化していないメタデータは、常に保持されます。 コメント(comment 列がない場合)、除外フラグ、その他のテーブルのメタデータは、どの同期でも触れられずに通過します。

外部での編集は尋ねられるだけで、サイレントにマージされることは決してない

ブリッジは自分が所有するテーブルに印を付け、最後の同期のフィンガープリントを記憶しています。それ以降にテーブルが変更されていた場合——誰かが Localization Tables ウィンドウで編集した、あるいは Unity 自身の Google Sheets 拡張で取り込んだ場合——次の同期は 止まって尋ねます: シートから上書きするか、差分レポートとともに中止するかを。サイレントなマージも、サイレントな上書きもありません。二つの操縦席によるワークフローが欲しいなら、代わりにもう一方の操縦席をシート経由にしてください——それこそが翻訳エクスポートの存在理由です。

孤児のキーは、デフォルトでは保持される

テーブルには存在するがシートにはもう存在しないキーは孤児です: それは保持され、孤児レポートに一覧化され、明示的なクリーンアップアクション(一括、またはキーごと)によってのみ削除できます。テーブルにシートを正確に鏡映しさせたい場合は、設定のトグルで 同期時に削除 へ切り替えられます。副作用として何かが破壊されることは決してありません。

パッケージなしの場合

Unity Localization パッケージは任意です。それがない場合:

ローカライズシートは 完全なシート です——オーサリング、検証、カバレッジ、Export、Push、xlsx、ウェブアプリ、キー定数、そして LocRef フィールドのすべてが、完全に機能します。
唯一待たされるのは StringTable 同期の出口 で、インストール通知(セッションにつき一回)を表示して止まります——Addressables と同じ案内のパターンであり、同じく決してプログラム的にはインストールされません。
すべてのアセンブリと、生成コードのすべての行が、パッケージなしでコンパイルされます。対応パッケージバージョン: 1.5 以降。

既存のテーブルをシートへ移行する

すでに Unity Localization を使っていますか? 逆方向インポーター が、既存の StringTable コレクションをローカライズシートに変換し、そのままインポートソースへ書き込んで自動的にインポートします——シートを作成するときと同じ経路です。レビューと編集は、その後で他のシートと同じように行えます。アクティブなソースにエディターから書き込めない場合、ファイルは Export 出力の隣に置かれ、移動するよう促す案内が添えられます。後でブリッジがそのシートを同じコレクションへ同期し直すとき、エントリの id は キー名の一致によって引き継がれます——シーンやプレハブの中にある既存の LocalizedString 参照は、移行を壊れることなく生き延びます。

翻訳ワークフロー

カバレッジ: 未翻訳のセルは拒否されるのではなく、報告される

空のロケールセルはエラーではありません——インポートは ロケールごとのカバレッジ(各ロケールが翻訳したキーの数と、欠けているキー)を報告し、どの出口も開いたままになります。テキストは少しずつ届くものであり、シートが未完成の翻訳のために止まることは決してありません。

ロケールレンズ

一度に一つの言語で作業していますか? ロケールレンズ が、どのロケール列を表示するかを切り替えます。これは @style の系統に属する表示用のメタデータであり——インポートのフィンガープリント、コード生成、そしてどの出力にも一切触れません。両方のホストで機能します。

翻訳エクスポートと部分的な再インポート

ある言語を翻訳者に渡すには、翻訳ワークブック をエクスポートします: ロケールを選ぶと、キー + ソーステキスト + コメント + ステータス列からなる xlsx が得られ、前回のエクスポート以降にソーステキストが変更されたエントリは outdated としてマークされます。ファイルが戻ってきたら、部分的なマージ として再インポートします: 行はキーで照合され、ロケール列だけが書き込まれます——構造、他のロケール、シートのその他すべては触れられないまま残ります。両方のホストで機能します。正直な非対称がひとつあります: ステータスの記憶は Unity プロジェクトの隣にあるマシンローカルのファイルに保存されるため、ブラウザーからエクスポートしたワークブックのステータス列は常に new になります。再インポート時の「古いソーステキストに対する翻訳」の通知は、ファイル自体が運んできたソーステキストと比較するため、どちらのホストでも機能します。

XLIFF と疑似ロケール

SheetForge は、XLIFF や疑似ローカライズを意図的に再実装しません——ブリッジが満たすテーブルは通常の Unity Localization のテーブルであるため、パッケージ自身の XLIFF エクスポート/インポートと疑似ロケールのツール群は、他のどんなプロジェクトとも同じようにそれらの上で機能します。ただし、一方向の権威については忘れないでください: それらのツールがテーブルの中に書き込んだ出力は、次の同期が尋ねてくる外部編集にあたります。翻訳を唯一の信頼できる情報源の中に留めておくには、テーブルにではなく、(上記の翻訳ワークブックを使って)シートを経由して戻してください。

関連する二つの境界を、正直に述べておきます: ブリッジがカバーするのは 文字列テーブルのみであり——アセットテーブルは認識済みのバックログ項目です——そして SheetForge は言語固有の Smart Format ヘルパーを同梱しません(例えば韓国語の助詞など)。smart 列はエントリを Smart String としてマークします。パッケージが提供する以上のフォーマッターは、パッケージ自身の拡張ポイントを通じて、あなた自身が書くものです。

ウェブアプリでは

ローカライズシートは、ブラウザーでも通常のシートです: オーサリング、検証、カバレッジ、インラインのソーステキスト付きの LocRef ピッカー、ミンティング、ロケールレンズ、そして翻訳ワークブックのすべてが web.sheetforge.workers.dev で機能します。StringTable の同期は Unity エディターの仕事です——ブラウザーには書き込み先となる Unity プロジェクトがなく、それができるふりもしません。