Files

tzdwindows 7 7badbb0d8e docs: 添加 Axis Innovators Box 框架完整 API 文档

- 新增浏览器模块技术文档，涵盖 BrowserCore、BrowserWindow 等核心组件
- 添加事件系统文档，包括 EventBus、GlobalEventBus 及各类事件定义
- 创建 LanguageManager 国际化管理器详细说明文档
- 新增 Log4j2OutputStream 标准输出重定向类文档
- 添加 Main 入口类启动流程与路由机制说明
- 创建 BrowserCreationCallback 回调接口使用指南
- 完善 AxisInnovatorsBox 主类架构与崩溃诊断系统文档

2026-01-03 08:46:19 +08:00

4.8 KiB

Raw Blame History

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

这是该类最强大的功能。插件无需修改主程序代码，即可通过以下流程添加翻译：

资源读取: 插件通过其 PluginDescriptor 从 JAR 包内部读取 .properties 文件。
动态合并: 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. 日志与反馈示例

当插件合并语言时，控制台会输出如下形式的“合并报告”，极大地方便了插件开发者的调试：

【语言合并报告】
▌合并来源：MyPlugin Resource -> system:zh_CN
▌变更统计：新增 10 条 / 更新 2 条
▌当前总量：156 条
▌关键示例：
✦ 新增条目：
   ▸ myplugin.button.start
   ▸ myplugin.menu.settings
✦ 更新条目：
   ▸ common.ok

6. 使用示例

6.1 在代码中获取翻译

// 建议在 UI 组件中使用
String title = LanguageManager.getLoadedLanguages().getText("mainWindow.title");
btn.setText(title);

6.2 插件注册语言

// 在插件初始化时调用
LanguageManager.registerPluginLanguage(
    this.descriptor, 
    "assets/lang/zh_CN.properties", 
    "system:zh_CN"
);

7. 注意事项

UTF-8 编码: 所有的 .properties 文件必须保存为 UTF-8 编码，否则在处理非 ASCII 字符（如中文、日文）时会出现乱码。
启动顺序: 建议在 Main 类中尽早调用 loadSavedLanguage()，以确保主窗口初始化时能正确显示本地化文本。
Key 冲突: 插件开发者应为 Key 添加前缀（如 plugin.id.text），以避免意外覆盖主程序或其他插件的翻译。

文档生成时间: 2026-01-02

4.8 KiB Raw Blame History Unescape Escape