https://github.com/gameframex/com.gameframex.unity.localization

Last synced: 8 months ago
JSON representation
Host: GitHub
URL: https://github.com/gameframex/com.gameframex.unity.localization
Owner: GameFrameX
License: apache-2.0
Created: 2024-04-10T05:07:12.000Z (about 2 years ago)
Default Branch: main
Last Pushed: 2025-06-23T11:45:40.000Z (12 months ago)
Last Synced: 2025-06-23T12:38:19.029Z (12 months ago)
Language: C#
Size: 67.4 KB
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project

README

          # GameFrameX Localization 本地化组件

**Localization 本地化组件** - 提供完整的多语言本地化解决方案，支持动态语言切换、字符串格式化和系统语言检测。

[![License](https://img.shields.io/github/license/AlianBlank/com.gameframex.unity.localization)](https://github.com/AlianBlank/com.gameframex.unity.localization/blob/main/LICENSE)

[![Unity Version](https://img.shields.io/badge/Unity-2021.3+-blue.svg)](https://unity3d.com/get-unity/download)

## 功能特性

- 🌍 **多语言支持** - 支持任意数量的语言和地区

- 🔄 **动态语言切换** - 运行时无缝切换语言

- 📝 **字符串格式化** - 支持最多16个参数的字符串格式化

- 🎯 **系统语言检测** - 自动检测并适配系统语言

- 📦 **字典管理** - 完整的本地化字典增删改查功能

- 🔧 **可扩展架构** - 支持自定义本地化辅助器

- 📱 **编辑器支持** - 编辑器模式下的语言预览功能

## 安装方式

### 方式一：通过 Package Manager 安装

1. 打开 Unity Package Manager

2. 点击 "+" 按钮，选择 "Add package from git URL"

3. 输入以下 URL：

```

https://github.com/AlianBlank/com.gameframex.unity.localization.git

```

### 方式二：通过 manifest.json 安装

在项目的 `Packages/manifest.json` 文件中添加：

```json

{

  "dependencies": {

    "com.gameframex.unity.localization": "https://github.com/AlianBlank/com.gameframex.unity.localization.git"

  }

}

```

### 方式三：本地安装

1. 下载源码到本地

2. 将整个文件夹放置到项目的 `Packages` 目录下

3. Unity 会自动识别并加载该包

## 依赖项

本组件依赖以下 GameFrameX 模块：

- `GameFrameX.Runtime` - 核心运行时模块

- `GameFrameX.Event.Runtime` - 事件系统模块

- `GameFrameX.Asset.Runtime` - 资源管理模块

- `GameFrameX.Setting.Runtime` - 设置管理模块

## 快速开始

### 1. 添加本地化组件

在场景中的 GameFrameX 管理器上添加 `LocalizationComponent` 组件：

```csharp

// 组件会自动初始化，无需手动代码

```

### 2. 基础用法

```csharp

// 获取本地化组件

var localization = GameEntry.GetComponent();

// 设置语言

localization.Language = "zh_CN"; // 中文

localization.Language = "en_US"; // 英文

// 获取本地化字符串

string text = localization.GetString("UI.Button.OK");

// 带参数的本地化字符串

string message = localization.GetString("UI.Message.Welcome", playerName);

string info = localization.GetString("UI.Info.Score", score, level);

```

### 3. 字典管理

```csharp

// 检查字典是否存在

bool exists = localization.HasRawString("UI.Button.Cancel");

// 获取原始字符串

string rawText = localization.GetRawString("UI.Button.Cancel");

// 添加字典项

localization.AddRawString("UI.Button.NewButton", "新按钮");

// 移除字典项

bool removed = localization.RemoveRawString("UI.Button.Cancel");

// 清空所有字典

localization.RemoveAllRawStrings();

```

### 4. 监听语言变化事件

```csharp

// 订阅语言变化事件

GameEntry.GetComponent().Subscribe(

    LocalizationLanguageChangeEventArgs.EventId, 

    OnLanguageChanged);

private void OnLanguageChanged(object sender, GameEventArgs e)

{

    var args = (LocalizationLanguageChangeEventArgs)e;

    Debug.Log($"语言从 {args.OldLanguage} 切换到 {args.Language}");

    

    // 更新UI显示

    RefreshUI();

}

```

## 高级功能

### 自定义本地化辅助器

创建自定义的本地化辅助器来扩展功能：

```csharp

public class CustomLocalizationHelper : LocalizationHelperBase

{

    public override string SystemLanguage

    {

        get

        {

            // 自定义系统语言检测逻辑

            return GetCustomSystemLanguage();

        }

    }

    

    private string GetCustomSystemLanguage()

    {

        // 实现自定义的系统语言检测

        // 例如：从服务器获取、用户偏好设置等

        return "zh_CN";

    }

}

```

### 组件配置

在 Inspector 面板中可以配置以下选项：

- **Editor Language**: 编辑器模式下使用的语言

- **Default Language**: 默认语言（加载失败时的备用语言）

- **Enable Load Dictionary Update Event**: 是否启用字典加载更新事件

- **Is Enable Editor Mode**: 是否启用编辑器模式

- **Localization Helper Type Name**: 本地化辅助器类型名称

- **Custom Localization Helper**: 自定义本地化辅助器实例

## API 参考

### LocalizationComponent 主要方法

| 方法 | 描述 |

|------|------|

| `GetString(string key)` | 获取本地化字符串 |

| `GetString(string key, T arg)` | 获取带1个参数的本地化字符串 |

| `GetString(string key, T1 arg1, T2 arg2)` | 获取带2个参数的本地化字符串 |

| `HasRawString(string key)` | 检查字典项是否存在 |

| `GetRawString(string key)` | 获取原始字典值 |

| `AddRawString(string key, string value)` | 添加字典项 |

| `RemoveRawString(string key)` | 移除字典项 |

| `RemoveAllRawStrings()` | 清空所有字典 |

### 属性

| 属性 | 类型 | 描述 |

|------|------|------|

| `Language` | string | 当前语言 |

| `DefaultLanguage` | string | 默认语言 |

| `SystemLanguage` | string | 系统语言（只读） |

| `DictionaryCount` | int | 字典项数量（只读） |

### 事件

| 事件 | 描述 |

|------|------|

| `LocalizationLanguageChangeEventArgs` | 语言变化事件 |

## 语言代码规范

本组件遵循 [RFC 5646](https://datatracker.ietf.org/doc/html/rfc5646) 语言标签标准：

- `zh_CN` - 简体中文

- `zh_TW` - 繁体中文

- `en_US` - 美式英语

- `en_GB` - 英式英语

- `ja_JP` - 日语

- `ko_KR` - 韩语

## 最佳实践

### 1. 字典键命名规范

建议使用层级化的命名方式：

```csharp

// UI相关

"UI.Button.OK"

"UI.Button.Cancel"

"UI.Message.Welcome"

// 游戏内容相关

"Game.Item.Sword"

"Game.Skill.Fireball"

"Game.Achievement.FirstWin"

// 错误信息相关

"Error.Network.Timeout"

"Error.Login.InvalidPassword"

```

### 2. 参数化字符串

合理使用参数化字符串，避免字符串拼接：

```csharp

// 推荐

"UI.Message.PlayerLevel" = "玩家等级：{0}"

localization.GetString("UI.Message.PlayerLevel", level);

// 不推荐

"UI.Message.PlayerLevel" = "玩家等级："

text = localization.GetString("UI.Message.PlayerLevel") + level;

```

### 3. 语言切换时机

在合适的时机进行语言切换，避免频繁切换：

```csharp

// 在游戏启动时设置

private void Start()

{

    var savedLanguage = PlayerPrefs.GetString("Language", "");

    if (string.IsNullOrEmpty(savedLanguage))

    {

        // 使用系统语言

        localization.Language = localization.SystemLanguage;

    }

    else

    {

        localization.Language = savedLanguage;

    }

}

// 保存用户选择的语言

private void SaveLanguagePreference(string language)

{

    PlayerPrefs.SetString("Language", language);

    PlayerPrefs.Save();

}

```

## 注意事项

1. **语言代码格式**：使用下划线分隔的格式（如 `zh_CN`），而不是连字符格式

2. **字典键大小写**：字典键区分大小写，建议统一使用规范的命名方式

3. **参数数量限制**：单个字符串最多支持16个格式化参数

4. **内存管理**：大量字典数据可能占用较多内存，建议按需加载

5. **线程安全**：组件操作应在主线程中进行

## 许可证

本项目采用 MIT 许可证和 Apache 许可证（版本 2.0）进行分发和使用。详细信息请查看 [LICENSE](LICENSE) 文件。

## 支持与反馈

- **GitHub Issues**: [提交问题](https://github.com/AlianBlank/com.gameframex.unity.localization/issues)

- **文档**: [查看完整文档](https://github.com/AlianBlank/com.gameframex.unity.localization/wiki)

---

**GameFrameX** - 让游戏开发更简单！
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/gameframex/com.gameframex.unity.localization

Awesome Lists containing this project

README
