tzdwindows 7
7badbb0d8e
- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件 - 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义 - 创建 LanguageManager 国际化管理器详细说明文档 - 新增 Log4j2OutputStream 标准输出重定向类文档 - 添加 Main 入口类启动流程与路由机制说明 - 创建 BrowserCreationCallback 回调接口使用指南 - 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档
109 lines
4.8 KiB
Markdown
109 lines
4.8 KiB
Markdown
这是一个专门为 `com.axis.innovators.box.register.LanguageManager` 类编写的技术介绍文档。
|
||
|
||
---
|
||
|
||
# LanguageManager 类技术文档
|
||
|
||
**包路径:** `com.axis.innovators.box.register.LanguageManager`
|
||
**主要功能:** 多语言国际化 (i18n) 管理器、插件语言合并系统
|
||
**作者:** tzdwindows 7
|
||
|
||
## 1. 概述
|
||
|
||
`LanguageManager` 是 **Axis Innovators Box** 框架的核心组件之一，负责管理应用程序的所有文本翻译和语言环境。它不仅支持内置的系统语言（中文、英文、日文），还具备高度的可扩展性，允许外部插件动态地将自己的语言包合并到主程序的语言池中。
|
||
|
||
该系统采用了 **Properties** 文件作为底层存储，通过 **UTF-8** 编码确保跨平台字符兼容性，并提供了完善的语言持久化（自动保存用户选择）功能。
|
||
|
||
## 2. 核心架构
|
||
|
||
### 2.1 语言描述类 (`Language` 内部类)
|
||
`Language` 是该管理器的基本数据单元，包含：
|
||
* **语言名称 (Language Name):** 用于 UI 显示的易读名称（如 "简体中文"）。
|
||
* **注册名 (Registered Name):** 内部唯一标识符（如 "system:zh_CN"）。
|
||
* **属性池 (Properties):** 存储键值对翻译数据的核心容器。
|
||
* **智能加载:** 能够从磁盘文件或 JAR 包输入流中加载数据。
|
||
|
||
### 2.2 存储与路径
|
||
* **语言文件夹:** 由 `FolderCreator.getLanguageFolder()` 定义。
|
||
* **持久化文件:** `saved_language.properties`，用于记录用户上一次关闭程序时使用的语言，实现启动自加载。
|
||
|
||
## 3. 核心功能特性
|
||
|
||
### 3.1 插件语言扩展机制 (`registerPluginLanguage`)
|
||
这是该类最强大的功能。插件无需修改主程序代码，即可通过以下流程添加翻译：
|
||
1. **资源读取:** 插件通过其 `PluginDescriptor` 从 JAR 包内部读取 `.properties` 文件。
|
||
2. **动态合并:** `LanguageManager` 会根据插件指定的 `targetRegisteredName`（如 "system:zh_CN"），自动将插件的翻译键值对并入主程序的对应语言对象中。
|
||
|
||
### 3.2 智能合并逻辑 (`addLanguage`)
|
||
当新语言资源并入时，系统会执行“差异化合并”：
|
||
* **新增条目:** 如果键不存在，则添加。
|
||
* **更新条目:** 如果键已存在，则用新值覆盖（允许插件覆盖系统默认文本）。
|
||
* **合并报告:** 自动生成详细的日志，记录新增和更新的数量，并列出前 5 个示例键。
|
||
|
||
### 3.3 语言切换与持久化
|
||
* **`loadLanguage(String name)`:** 切换当前语言并立即将选择写入磁盘。
|
||
* **`loadSavedLanguage()`:** 在程序启动时调用，恢复用户偏好的语言环境。
|
||
|
||
## 4. API 说明
|
||
|
||
### 4.1 管理器核心方法
|
||
|
||
| 方法 | 描述 |
|
||
| :--- | :--- |
|
||
| `static void registerPluginLanguage(...)` | **插件专用接口**。从插件资源中加载并合并语言包。 |
|
||
| `static void addLanguage(Language lang)` | 将一个 Language 对象合并到现有的语言列表中。 |
|
||
| `static void loadLanguage(String name)` | 设置当前激活的语言。 |
|
||
| `static Language getLoadedLanguages()` | 获取当前正在使用的 Language 对象。 |
|
||
| `static List<Language> getLanguages()` | 获取系统当前支持的所有语言列表。 |
|
||
|
||
### 4.2 Language 对象常用方法
|
||
|
||
| 方法 | 描述 |
|
||
| :--- | :--- |
|
||
| `String getText(String key)` | **最常用方法**。根据键获取翻译文本。如果键不存在，则返回键名本身（防止 UI 出现空白）。 |
|
||
| `void addText(String key, String val)` | 动态添加单条翻译。 |
|
||
|
||
## 5. 日志与反馈示例
|
||
|
||
当插件合并语言时，控制台会输出如下形式的“合并报告”，极大地方便了插件开发者的调试：
|
||
|
||
```text
|
||
【语言合并报告】
|
||
▌合并来源：MyPlugin Resource -> system:zh_CN
|
||
▌变更统计：新增 10 条 / 更新 2 条
|
||
▌当前总量：156 条
|
||
▌关键示例：
|
||
✦ 新增条目：
|
||
▸ myplugin.button.start
|
||
▸ myplugin.menu.settings
|
||
✦ 更新条目：
|
||
▸ common.ok
|
||
```
|
||
|
||
## 6. 使用示例
|
||
|
||
### 6.1 在代码中获取翻译
|
||
```java
|
||
// 建议在 UI 组件中使用
|
||
String title = LanguageManager.getLoadedLanguages().getText("mainWindow.title");
|
||
btn.setText(title);
|
||
```
|
||
|
||
### 6.2 插件注册语言
|
||
```java
|
||
// 在插件初始化时调用
|
||
LanguageManager.registerPluginLanguage(
|
||
this.descriptor,
|
||
"assets/lang/zh_CN.properties",
|
||
"system:zh_CN"
|
||
);
|
||
```
|
||
|
||
## 7. 注意事项
|
||
|
||
1. **UTF-8 编码:** 所有的 `.properties` 文件必须保存为 UTF-8 编码，否则在处理非 ASCII 字符（如中文、日文）时会出现乱码。
|
||
2. **启动顺序:** 建议在 `Main` 类中尽早调用 `loadSavedLanguage()`，以确保主窗口初始化时能正确显示本地化文本。
|
||
3. **Key 冲突:** 插件开发者应为 Key 添加前缀（如 `plugin.id.text`），以避免意外覆盖主程序或其他插件的翻译。
|
||
|
||
---
|
||
*文档生成时间: 2026-01-02* |