{"id":21358877,"url":"https://github.com/gameframex/com.gameframex.unity.localization","last_synced_at":"2025-10-16T05:56:54.922Z","repository":{"id":232569758,"uuid":"784562145","full_name":"GameFrameX/com.gameframex.unity.localization","owner":"GameFrameX","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-23T11:45:40.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-23T12:38:19.029Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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.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}},"created_at":"2024-04-10T05:07:12.000Z","updated_at":"2025-06-23T11:45:44.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":6,"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":279160839,"owners_count":26116817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"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":[],"created_at":"2024-11-22T05:22:44.026Z","updated_at":"2025-10-16T05:56:54.917Z","avatar_url":"https://github.com/GameFrameX.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GameFrameX Localization 本地化组件\n\n**Localization 本地化组件** - 提供完整的多语言本地化解决方案，支持动态语言切换、字符串格式化和系统语言检测。\n\n[![License](https://img.shields.io/github/license/AlianBlank/com.gameframex.unity.localization)](https://github.com/AlianBlank/com.gameframex.unity.localization/blob/main/LICENSE)\n[![Unity Version](https://img.shields.io/badge/Unity-2021.3+-blue.svg)](https://unity3d.com/get-unity/download)\n\n## 功能特性\n\n- 🌍 **多语言支持** - 支持任意数量的语言和地区\n- 🔄 **动态语言切换** - 运行时无缝切换语言\n- 📝 **字符串格式化** - 支持最多16个参数的字符串格式化\n- 🎯 **系统语言检测** - 自动检测并适配系统语言\n- 📦 **字典管理** - 完整的本地化字典增删改查功能\n- 🔧 **可扩展架构** - 支持自定义本地化辅助器\n- 📱 **编辑器支持** - 编辑器模式下的语言预览功能\n\n## 安装方式\n\n### 方式一：通过 Package Manager 安装\n\n1. 打开 Unity Package Manager\n2. 点击 \"+\" 按钮，选择 \"Add package from git URL\"\n3. 输入以下 URL：\n```\nhttps://github.com/AlianBlank/com.gameframex.unity.localization.git\n```\n\n### 方式二：通过 manifest.json 安装\n\n在项目的 `Packages/manifest.json` 文件中添加：\n\n```json\n{\n  \"dependencies\": {\n    \"com.gameframex.unity.localization\": \"https://github.com/AlianBlank/com.gameframex.unity.localization.git\"\n  }\n}\n```\n\n### 方式三：本地安装\n\n1. 下载源码到本地\n2. 将整个文件夹放置到项目的 `Packages` 目录下\n3. Unity 会自动识别并加载该包\n\n## 依赖项\n\n本组件依赖以下 GameFrameX 模块：\n\n- `GameFrameX.Runtime` - 核心运行时模块\n- `GameFrameX.Event.Runtime` - 事件系统模块\n- `GameFrameX.Asset.Runtime` - 资源管理模块\n- `GameFrameX.Setting.Runtime` - 设置管理模块\n\n## 快速开始\n\n### 1. 添加本地化组件\n\n在场景中的 GameFrameX 管理器上添加 `LocalizationComponent` 组件：\n\n```csharp\n// 组件会自动初始化，无需手动代码\n```\n\n### 2. 基础用法\n\n```csharp\n// 获取本地化组件\nvar localization = GameEntry.GetComponent\u003cLocalizationComponent\u003e();\n\n// 设置语言\nlocalization.Language = \"zh_CN\"; // 中文\nlocalization.Language = \"en_US\"; // 英文\n\n// 获取本地化字符串\nstring text = localization.GetString(\"UI.Button.OK\");\n\n// 带参数的本地化字符串\nstring message = localization.GetString(\"UI.Message.Welcome\", playerName);\nstring info = localization.GetString(\"UI.Info.Score\", score, level);\n```\n\n### 3. 字典管理\n\n```csharp\n// 检查字典是否存在\nbool exists = localization.HasRawString(\"UI.Button.Cancel\");\n\n// 获取原始字符串\nstring rawText = localization.GetRawString(\"UI.Button.Cancel\");\n\n// 添加字典项\nlocalization.AddRawString(\"UI.Button.NewButton\", \"新按钮\");\n\n// 移除字典项\nbool removed = localization.RemoveRawString(\"UI.Button.Cancel\");\n\n// 清空所有字典\nlocalization.RemoveAllRawStrings();\n```\n\n### 4. 监听语言变化事件\n\n```csharp\n// 订阅语言变化事件\nGameEntry.GetComponent\u003cEventComponent\u003e().Subscribe(\n    LocalizationLanguageChangeEventArgs.EventId, \n    OnLanguageChanged);\n\nprivate void OnLanguageChanged(object sender, GameEventArgs e)\n{\n    var args = (LocalizationLanguageChangeEventArgs)e;\n    Debug.Log($\"语言从 {args.OldLanguage} 切换到 {args.Language}\");\n    \n    // 更新UI显示\n    RefreshUI();\n}\n```\n\n## 高级功能\n\n### 自定义本地化辅助器\n\n创建自定义的本地化辅助器来扩展功能：\n\n```csharp\npublic class CustomLocalizationHelper : LocalizationHelperBase\n{\n    public override string SystemLanguage\n    {\n        get\n        {\n            // 自定义系统语言检测逻辑\n            return GetCustomSystemLanguage();\n        }\n    }\n    \n    private string GetCustomSystemLanguage()\n    {\n        // 实现自定义的系统语言检测\n        // 例如：从服务器获取、用户偏好设置等\n        return \"zh_CN\";\n    }\n}\n```\n\n### 组件配置\n\n在 Inspector 面板中可以配置以下选项：\n\n- **Editor Language**: 编辑器模式下使用的语言\n- **Default Language**: 默认语言（加载失败时的备用语言）\n- **Enable Load Dictionary Update Event**: 是否启用字典加载更新事件\n- **Is Enable Editor Mode**: 是否启用编辑器模式\n- **Localization Helper Type Name**: 本地化辅助器类型名称\n- **Custom Localization Helper**: 自定义本地化辅助器实例\n\n## API 参考\n\n### LocalizationComponent 主要方法\n\n| 方法 | 描述 |\n|------|------|\n| `GetString(string key)` | 获取本地化字符串 |\n| `GetString\u003cT\u003e(string key, T arg)` | 获取带1个参数的本地化字符串 |\n| `GetString\u003cT1,T2\u003e(string key, T1 arg1, T2 arg2)` | 获取带2个参数的本地化字符串 |\n| `HasRawString(string key)` | 检查字典项是否存在 |\n| `GetRawString(string key)` | 获取原始字典值 |\n| `AddRawString(string key, string value)` | 添加字典项 |\n| `RemoveRawString(string key)` | 移除字典项 |\n| `RemoveAllRawStrings()` | 清空所有字典 |\n\n### 属性\n\n| 属性 | 类型 | 描述 |\n|------|------|------|\n| `Language` | string | 当前语言 |\n| `DefaultLanguage` | string | 默认语言 |\n| `SystemLanguage` | string | 系统语言（只读） |\n| `DictionaryCount` | int | 字典项数量（只读） |\n\n### 事件\n\n| 事件 | 描述 |\n|------|------|\n| `LocalizationLanguageChangeEventArgs` | 语言变化事件 |\n\n## 语言代码规范\n\n本组件遵循 [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646) 语言标签标准：\n\n- `zh_CN` - 简体中文\n- `zh_TW` - 繁体中文\n- `en_US` - 美式英语\n- `en_GB` - 英式英语\n- `ja_JP` - 日语\n- `ko_KR` - 韩语\n\n## 最佳实践\n\n### 1. 字典键命名规范\n\n建议使用层级化的命名方式：\n\n```csharp\n// UI相关\n\"UI.Button.OK\"\n\"UI.Button.Cancel\"\n\"UI.Message.Welcome\"\n\n// 游戏内容相关\n\"Game.Item.Sword\"\n\"Game.Skill.Fireball\"\n\"Game.Achievement.FirstWin\"\n\n// 错误信息相关\n\"Error.Network.Timeout\"\n\"Error.Login.InvalidPassword\"\n```\n\n### 2. 参数化字符串\n\n合理使用参数化字符串，避免字符串拼接：\n\n```csharp\n// 推荐\n\"UI.Message.PlayerLevel\" = \"玩家等级：{0}\"\nlocalization.GetString(\"UI.Message.PlayerLevel\", level);\n\n// 不推荐\n\"UI.Message.PlayerLevel\" = \"玩家等级：\"\ntext = localization.GetString(\"UI.Message.PlayerLevel\") + level;\n```\n\n### 3. 语言切换时机\n\n在合适的时机进行语言切换，避免频繁切换：\n\n```csharp\n// 在游戏启动时设置\nprivate void Start()\n{\n    var savedLanguage = PlayerPrefs.GetString(\"Language\", \"\");\n    if (string.IsNullOrEmpty(savedLanguage))\n    {\n        // 使用系统语言\n        localization.Language = localization.SystemLanguage;\n    }\n    else\n    {\n        localization.Language = savedLanguage;\n    }\n}\n\n// 保存用户选择的语言\nprivate void SaveLanguagePreference(string language)\n{\n    PlayerPrefs.SetString(\"Language\", language);\n    PlayerPrefs.Save();\n}\n```\n\n## 注意事项\n\n1. **语言代码格式**：使用下划线分隔的格式（如 `zh_CN`），而不是连字符格式\n2. **字典键大小写**：字典键区分大小写，建议统一使用规范的命名方式\n3. **参数数量限制**：单个字符串最多支持16个格式化参数\n4. **内存管理**：大量字典数据可能占用较多内存，建议按需加载\n5. **线程安全**：组件操作应在主线程中进行\n\n## 许可证\n\n本项目采用 MIT 许可证和 Apache 许可证（版本 2.0）进行分发和使用。详细信息请查看 [LICENSE](LICENSE) 文件。\n\n## 支持与反馈\n\n- **GitHub Issues**: [提交问题](https://github.com/AlianBlank/com.gameframex.unity.localization/issues)\n- **文档**: [查看完整文档](https://github.com/AlianBlank/com.gameframex.unity.localization/wiki)\n\n---\n\n**GameFrameX** - 让游戏开发更简单！","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"}