i18n (国際化) ガイド¶

概要¶

本プロジェクトでは Godot の組み込み翻訳システム (tr()) を使用し、CSV ベースの翻訳ファイルで日本語・英語の 2 言語をサポートする。

ファイル構成¶

translations/
  translations.csv         ← 翻訳元ファイル（このファイルを編集する）
  translations.ja.translation  ← Godot が自動生成（Git 管理外）
  translations.en.translation  ← Godot が自動生成（Git 管理外）

翻訳キーの命名規約¶

翻訳キーは 大文字スネークケース で統一し、以下のパターンに従う。

静的データ（Resource）¶

データ種別	表示名キー	説明文キー
ユニット	`UNIT_{ID}_NAME`	`UNIT_{ID}_DESC`
スキル	`SKILL_{ID}_NAME`	`SKILL_{ID}_DESC`
ステージ	`STAGE_{ID}_NAME`	`STAGE_{ID}_DESC`

{ID} は Resource の id プロパティ（StringName）を to_upper() したもの
例: id = &"fire_mage" → UNIT_FIRE_MAGE_NAME, UNIT_FIRE_MAGE_DESC

UI テキスト（将来用）¶

カテゴリ	パターン	例
画面タイトル	`UI_{SCREEN}_TITLE`	`UI_HOME_TITLE`
ボタン	`UI_{SCREEN}_{ACTION}_BTN`	`UI_BATTLE_START_BTN`
メッセージ	`MSG_{CONTEXT}_{DETAIL}`	`MSG_SAVE_SUCCESS`

CSV 編集ルール¶

1 行目はヘッダー: keys,ja,en の順序を変えない
カンマ区切り: フィールド内にカンマを含む場合はダブルクォートで囲む
UTF-8 BOM なし: エンコーディングは UTF-8（BOM なし）で保存する
キーの一意性: 同じキーを複数行に定義しない

コード内での使用¶

各 Resource クラスの get_display_name() / get_description() メソッドが翻訳キーから自動的にテキストを取得する。実装例は scripts/data/unit_data.gd を参照。

言語の切り替え¶

# ロケールを日本語に設定
TranslationServer.set_locale("ja")

# ロケールを英語に設定
TranslationServer.set_locale("en")

# OS のロケールを自動検出
var locale := OS.get_locale_language()
TranslationServer.set_locale(locale)

新しい翻訳エントリの追加手順¶

translations/translations.csv を開く
新しい行を追加（KEY,日本語テキスト,English text）
Godot エディタで再インポート（自動）
tr("KEY") で参照可能になる

注意事項¶

tr() に存在しないキーを渡すと、キー文字列がそのまま返される（サイレント失敗）
新しい Resource を追加した際は、忘れずに対応する翻訳エントリを CSV に追加すること