这是一个专门为 `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*