{"id":21358877,"url":"https://github.com/gameframex/com.gameframex.unity.localization","last_synced_at":"2026-07-13T01:31:22.361Z","repository":{"id":232569758,"uuid":"784562145","full_name":"GameFrameX/com.gameframex.unity.localization","owner":"GameFrameX","description":"GameFrameX Unity Localization component providing multi-language support with dynamic locale switching and text asset management","archived":false,"fork":false,"pushed_at":"2026-06-01T11:54:53.000Z","size":122,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-01T12:16:15.504Z","etag":null,"topics":["csharp","game-framework","i18n","localization","multi-language","unity","upm-package"],"latest_commit_sha":null,"homepage":"https://gameframex.doc.alianblank.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GameFrameX.png","metadata":{"files":{"readme":"README.ja.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-04-10T05:07:12.000Z","updated_at":"2026-06-01T11:54:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"52952df8-3392-4b0b-9aa8-21a45bc30c38","html_url":"https://github.com/GameFrameX/com.gameframex.unity.localization","commit_stats":null,"previous_names":["alianblank/com.alianblank.gameframex.unity.localization","gameframex/com.gameframex.unity.localization"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/GameFrameX/com.gameframex.unity.localization","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2Fcom.gameframex.unity.localization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2Fcom.gameframex.unity.localization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2Fcom.gameframex.unity.localization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2Fcom.gameframex.unity.localization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GameFrameX","download_url":"https://codeload.github.com/GameFrameX/com.gameframex.unity.localization/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GameFrameX%2Fcom.gameframex.unity.localization/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35407393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-12T02:00:06.386Z","response_time":87,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","game-framework","i18n","localization","multi-language","unity","upm-package"],"created_at":"2024-11-22T05:22:44.026Z","updated_at":"2026-07-13T01:31:22.350Z","avatar_url":"https://github.com/GameFrameX.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://download.alianblank.com/gameframex/gameframex_logo_320.png\" alt=\"Game Frame X Logo\" width=\"160\" /\u003e\n\n# Game Frame X Localization\n\n[![License](https://img.shields.io/github/license/GameFrameX/com.gameframex.unity.localization)](https://github.com/GameFrameX/com.gameframex.unity.localization/blob/main/LICENSE.md)\n[![Version](https://img.shields.io/github/v/release/GameFrameX/com.gameframex.unity.localization)](https://github.com/GameFrameX/com.gameframex.unity.localization/releases)\n[![Unity Version](https://img.shields.io/badge/Unity-2019.4-black?logo=unity)](https://unity.com/)\n[![Documentation](https://img.shields.io/badge/Documentation-docs-blue)](https://gameframex.doc.alianblank.com)\n\nインディゲーム開発者向けオールインワンソリューション · インディ開発者の夢を支援\n\n\u003cbr /\u003e\n\n[ドキュメント](https://gameframex.doc.alianblank.com) · [クイックスタート](#クイックスタート) · QQグループ: 467608841 / 233840761\n\n\u003cbr /\u003e\n\n[English](README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | **日本語** | [한국어](README.ko.md)\n\n\u003c/div\u003e\n\n## 目次\n\n- [プロジェクト概要](#プロジェクト概要)\n- [機能一覧](#機能一覧)\n- [クイックスタート](#クイックスタート)\n  - [動作環境](#動作環境)\n  - [インストール](#インストール)\n  - [コンポーネントの設定](#コンポーネントの設定)\n- [使い方](#使い方)\n  - [コンポーネントの取得](#コンポーネントの取得)\n  - [言語管理](#言語管理)\n  - [ローカライズされた文字列の取得](#ローカライズされた文字列の取得)\n  - [パラメータ付きフォーマット](#パラメータ付きフォーマット)\n  - [辞書管理](#辞書管理)\n  - [言語変更の監視](#言語変更の監視)\n  - [言語コード定数](#言語コード定数)\n- [エディタ Inspector](#エディタ-inspector)\n- [イベントリファレンス](#イベントリファレンス)\n- [Helper の拡張](#helper-の拡張)\n- [依存関係](#依存関係)\n- [ドキュメントとリソース](#ドキュメントとリソース)\n- [ライセンス](#ライセンス)\n\n## プロジェクト概要\n\nGame Frame X Localization は、GameFrameX フレームワークに基づく Unity ローカリゼーションパッケージです。辞書ベースの文字列翻訳、パラメータ付きフォーマット（最大16個の型付きパラメータ）、イベント通知付きのランタイム言語切り替え、システム言語またはデフォルト言語への自動フォールバック、Setting システムによる言語設定の永続化を備えた、完全な多言語ローカリゼーションソリューションを提供します。\n\n## 機能一覧\n\n- **辞書ベースのローカリゼーション** — ランタイムでキーと値の翻訳ペアを追加、照会、削除\n- **パラメータ付き文字列フォーマット** — 1〜16個の型付きパラメータを持つジェネリック `GetString` オーバーロードと、`params object[]` オーバーロードを提供\n- **ランタイム言語切り替え** — いつでもアクティブ言語を変更可能、イベントで全リスナーに通知\n- **システム言語検出** — `CultureInfo` を使用してデバイスのシステム言語を自動検出\n- **言語設定の永続化** — 選択された言語とデフォルト言語は Setting コンポーネントを通じて自動保存\n- **エディタモード対応** — Unity エディタでテスト用に言語設定を上書き可能\n- **180以上の言語コード定数** — 組み込みの `LocalizationCode` 静的クラスで世界の主要地域の言語をカバー\n- **カスタム Helper サポート** — `LocalizationHelperBase` を継承してシステム言語検出ロジックを上書き\n\n## クイックスタート\n\n### インストール\n\n以下のいずれかの方法を選択してください：\n\n1. Unity プロジェクトの `Packages/manifest.json` を編集し、`scopedRegistries` セクションを追加してください：\n   ```json\n   {\n     \"scopedRegistries\": [\n       {\n         \"name\": \"GameFrameX\",\n         \"url\": \"https://gameframex.upm.alianblank.uk\",\n         \"scopes\": [\n           \"com.gameframex\"\n         ]\n       }\n     ],\n     \"dependencies\": {\n       \"com.gameframex.unity.localization\": \"2.3.0\"\n     }\n   }\n   ```\n\n   `scopes` は、どのパッケージをこのレジストリから解決するかを制御します。`com.gameframex` で始まるパッケージのみがこのレジストリから取得されます。\n\n2. `manifest.json` の `dependencies` に直接追加：\n   ```json\n   {\n      \"com.gameframex.unity.localization\": \"https://github.com/gameframex/com.gameframex.unity.localization.git\"\n   }\n   ```\n3. Unity の **Package Manager** で **Git URL** を使用して追加：`https://github.com/gameframex/com.gameframex.unity.localization.git`\n4. リポジトリを Unity プロジェクトの `Packages` ディレクトリにクローンしてください。自動的に読み込まれます。\n## 使用例\n\n### コンポーネントの取得\n\n```csharp\nusing GameFrameX.Localization.Runtime;\n\n// 標準: GameEntry 経由で取得\nvar localization = GameEntry.GetComponent\u003cLocalizationComponent\u003e();\n```\n\n### 言語管理\n\n```csharp\n// 現在のアクティブ言語を取得（未設定の場合はシステム言語を返す）\nstring currentLang = localization.Language;\n\n// アクティブ言語を設定（変更イベントを発火、設定に自動保存）\nlocalization.Language = \"zh_CN\";\nlocalization.Language = \"en_US\";\nlocalization.Language = \"ja_JP\";\n\n// デフォルト/フォールバック言語を取得\nstring defaultLang = localization.DefaultLanguage;\n\n// 新しいデフォルト言語を設定\nlocalization.DefaultLanguage = \"en_US\";\n\n// デバイスから検出されたシステム言語を取得\nstring sysLang = localization.SystemLanguage;\n\n// 読み込み済みの辞書エントリ総数を取得\nint count = localization.DictionaryCount;\n```\n\n### ローカライズされた文字列の取得\n\n```csharp\n// 単純なキー検索\n// キーが見つからない場合、\"\u003cNoKey\u003e{key}\" を返す\nstring okText = localization.GetString(\"UI.Button.OK\");\nstring cancelText = localization.GetString(\"UI.Button.Cancel\");\n\n// 値を取得する前にキーの存在を確認\nif (localization.HasRawString(\"UI.Button.Confirm\"))\n{\n    string confirmText = localization.GetString(\"UI.Button.Confirm\");\n}\n```\n\n### パラメータ付きフォーマット\n\n本パッケージは、パラメータ付きフォーマットのための複数の `GetString` オーバーロードを提供します。辞書の値には標準的な .NET フォーマットプレースホルダー（`{0}`、`{1}` など）を使用してください。\n\n```csharp\n// 辞書に以下が含まれていると仮定：\n// \"UI.Message.Welcome\" = \"ようこそ、{0}さん！\"\n// \"UI.Info.Score\"     = \"プレイヤー {0} はレベル {2} で {1} 点を獲得しました！\"\n// \"UI.Shop.Buy\"       = \"{0} x {1} を {2} コインで購入、割引 {3:P}、合計 {4:C}\"\n\n// params object[] オーバーロードを使用\nstring welcome = localization.GetString(\"UI.Message.Welcome\", playerName);\n\n// ジェネリックオーバーロードを使用（推奨 — 値型のボクシングを回避）\nstring info = localization.GetString\u003cstring, int, int\u003e(\"UI.Info.Score\", playerName, score, level);\n\n// 最大16個の型付きパラメータまで対応\nstring shopMsg = localization.GetString\u003cstring, int, int, float, decimal\u003e(\n    \"UI.Shop.Buy\", itemName, quantity, unitPrice, discount, total);\n```\n\n**エラー処理：** フォーマット文字列のプレースホルダーと提供された引数が一致しない場合、結果は `\u003cError\u003e` で始まり、診断情報が付加されます。キーが存在しない場合、結果は `\u003cNoKey\u003e{key}` になります。\n\n### 辞書管理\n\nランタイムで翻訳エントリを管理：\n\n```csharp\n// 新しいエントリを追加（キーが既に存在する、または null/空の場合は false を返す）\nbool added = localization.AddRawString(\"UI.Button.NewButton\", \"新しいボタン\");\nif (!added)\n{\n    // キーが既に存在するか無効\n}\n\n// 存在確認\nbool exists = localization.HasRawString(\"UI.Button.NewButton\");\n\n// 生の（フォーマットされていない）値を取得（見つからない場合は null）\nstring rawText = localization.GetRawString(\"UI.Button.NewButton\");\n\n// 特定のエントリを削除（キーが存在しない場合は false）\nbool removed = localization.RemoveRawString(\"UI.Button.NewButton\");\n\n// 全エントリを削除\nlocalization.RemoveAllRawStrings();\n```\n\n### 言語変更の監視\n\nアクティブ言語が変更されると（`localization.Language = ...` 経由）、コンポーネントはイベントシステムを通じて `LocalizationLanguageChangeEventArgs` イベントを発火します。\n\n```csharp\nusing GameFrameX.Event.Runtime;\nusing GameFrameX.Localization.Runtime;\n\npublic class MyLanguageHandler : MonoBehaviour\n{\n    private EventComponent m_EventComponent;\n    private LocalizationComponent m_LocalizationComponent;\n\n    void Start()\n    {\n        m_EventComponent = GameEntry.GetComponent\u003cEventComponent\u003e();\n        m_LocalizationComponent = GameEntry.GetComponent\u003cLocalizationComponent\u003e();\n\n        // 言語変更イベントを購読\n        m_EventComponent.Subscribe(\n            LocalizationLanguageChangeEventArgs.EventId, OnLanguageChanged);\n    }\n\n    void OnDestroy()\n    {\n        // 購読解除\n        m_EventComponent.Unsubscribe(\n            LocalizationLanguageChangeEventArgs.EventId, OnLanguageChanged);\n    }\n\n    private void OnLanguageChanged(object sender, GameEventArgs e)\n    {\n        var args = (LocalizationLanguageChangeEventArgs)e;\n\n        // 変更前の言語コード（例：\"ja_JP\"）\n        string oldLang = args.OldLanguage;\n\n        // 変更後の言語コード（例：\"en_US\"）\n        string newLang = args.Language;\n\n        // ここで全 UI テキストを更新\n        RefreshAllText();\n    }\n\n    private void RefreshAllText()\n    {\n        // 新しい言語で全ローカライズ文字列を再取得\n        // 例：myText.text = m_LocalizationComponent.GetString(\"UI.MainMenu.Title\");\n    }\n}\n```\n\n### 言語コード定数\n\n`LocalizationCode` 静的クラスは、地域別に分類された 180 以上の定義済み言語コード定数を提供します。`言語_地域` 形式に従います（例：`ja_JP`、`en_US`）。\n\n```csharp\nusing GameFrameX.Localization.Runtime;\n\n// 東アジア\nlocalization.Language = LocalizationCode.ChineseSimplified;    // \"zh_CN\"\nlocalization.Language = LocalizationCode.ChineseTraditionalTW; // \"zh_TW\"\nlocalization.Language = LocalizationCode.Japanese;             // \"ja_JP\"\nlocalization.Language = LocalizationCode.Korean;               // \"ko_KR\"\n\n// 英語バリアント\nlocalization.Language = LocalizationCode.English;    // \"en_US\"\nlocalization.Language = LocalizationCode.EnglishUK;  // \"en_GB\"\nlocalization.Language = LocalizationCode.EnglishAU;  // \"en_AU\"\n\n// ヨーロッパ\nlocalization.Language = LocalizationCode.French;     // \"fr_FR\"\nlocalization.Language = LocalizationCode.German;     // \"de_DE\"\nlocalization.Language = LocalizationCode.Italian;    // \"it_IT\"\nlocalization.Language = LocalizationCode.Spanish;    // \"es_ES\"\nlocalization.Language = LocalizationCode.Portuguese; // \"pt_PT\"\nlocalization.Language = LocalizationCode.Russian;    // \"ru_RU\"\n\n// 中東・西アジア\nlocalization.Language = LocalizationCode.Arabic;  // \"ar_SA\"\nlocalization.Language = LocalizationCode.Hebrew;   // \"he_IL\"\nlocalization.Language = LocalizationCode.Persian;  // \"fa_IR\"\nlocalization.Language = LocalizationCode.Turkish;  // \"tr_TR\"\n\n// 南アジア・東南アジア\nlocalization.Language = LocalizationCode.Hindi;      // \"hi_IN\"\nlocalization.Language = LocalizationCode.Thai;       // \"th_TH\"\nlocalization.Language = LocalizationCode.Vietnamese; // \"vi_VN\"\nlocalization.Language = LocalizationCode.Indonesian; // \"id_ID\"\n\n// アフリカ\nlocalization.Language = LocalizationCode.Swahili; // \"sw_TZ\"\n\n// オセアニア\nlocalization.Language = LocalizationCode.Maori; // \"mi_NZ\"\n```\n\n多くの言語には地域バリアントが用意されています（例：`SpanishMX`、`PortugueseBR`、`ArabicEG`、`FrenchCA` など）。完全なリストは `LocalizationCode.cs` を参照してください。\n\n## エディタ Inspector\n\n`LocalizationComponentInspector` は以下のオプションを備えたカスタム Inspector を提供します：\n\n| フィールド | 説明 |\n|-----------|------|\n| **Localization Helper** | Helper の型を選択、またはカスタム Helper インスタンスを割り当て |\n| **Default Language** | フォールバック言語コード |\n| **Enable Editor Mode** | チェックすると、Play Mode でシステム言語の代わりに Editor Language を使用 |\n| **Editor Language** | エディタモードで使用する言語コード |\n| **Language**（Play Mode のみ） | ランタイムでの現在のアクティブ言語を表示 |\n| **System Language**（Play Mode のみ） | 検出されたシステム言語を表示 |\n\n## イベントリファレンス\n\n| イベント | クラス | 発火条件 | 主なフィールド |\n|---------|--------|---------|---------------|\n| 言語変更 | `LocalizationLanguageChangeEventArgs` | `Language` プロパティが設定された時 | `OldLanguage`、`Language` |\n| 辞書読み込み成功 | `LoadDictionarySuccessEventArgs` | 辞書アセットの読み込み完了 | `DictionaryAssetName`、`Duration`、`UserData` |\n| 辞書読み込み失敗 | `LoadDictionaryFailureEventArgs` | 辞書アセットの読み込み失敗 | `DictionaryAssetName`、`ErrorMessage`、`UserData` |\n| 辞書読み込み進捗 | `LoadDictionaryUpdateEventArgs` | 辞書アセットの読み込み進捗更新 | `DictionaryAssetName`、`Progress`、`UserData` |\n\n全イベントクラスは GameFrameX 参照プールを使用し、ゼロアロケーションでイベントを発火します。\n\n## Helper の拡張\n\nシステム言語検出をカスタマイズする場合（例：バックエンドサービスやカスタム設定からの読み取り）、`LocalizationHelperBase` を継承したクラスを作成します：\n\n```csharp\nusing GameFrameX.Localization.Runtime;\n\npublic class CustomLocalizationHelper : LocalizationHelperBase\n{\n    public override string SystemLanguage\n    {\n        get\n        {\n            // ここにカスタムロジックを実装\n            // 例：設定ファイルやリモート API から読み取り\n            return \"en_US\";\n        }\n    }\n}\n```\n\nその後、Inspector の **Localization Helper** フィールドで割り当てるか、`m_LocalizationHelperTypeName` に完全な型名を設定します。\n\n## 依存関係\n\n| パッケージ | バージョン | 説明 |\n|-----------|-----------|------|\n| `com.gameframex.unity` | 1.1.1+ | GameFrameX コアフレームワーク |\n| `com.gameframex.unity.asset` | 1.0.6+ | アセット管理モジュール |\n| `com.gameframex.unity.event` | 1.0.0+ | イベントシステムモジュール |\n| `com.gameframex.unity.setting` | 1.5.0+ | 設定永続化モジュール |\n\n## ドキュメントとリソース\n\n- ドキュメント: https://gameframex.doc.alianblank.com\n- リポジトリ: https://github.com/GameFrameX/com.gameframex.unity.localization\n- Issues: https://github.com/GameFrameX/com.gameframex.unity.localization/issues\n\n\n## コミュニティとサポート\n\n- QQグループ: 467608841 / 233840761\n\n## 変更履歴\n\n[Releases](https://github.com/GameFrameX/gameframex/com.gameframex.unity.localization/releases) で変更履歴を確認してください。\n## ライセンス\n\n詳しくは [LICENSE.md](LICENSE.md) をご参照ください。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgameframex%2Fcom.gameframex.unity.localization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgameframex%2Fcom.gameframex.unity.localization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgameframex%2Fcom.gameframex.unity.localization/lists"}