336 lines
7.3 KiB
Markdown
336 lines
7.3 KiB
Markdown
# `MiniI18N` 国际化工具技术文档
|
||
|
||
```markdown
|
||
# MiniI18N - 轻量级多语言支持模块
|
||
|
||
`MiniI18N` 是一个基于 Python 的轻量级国际化（i18n）工具，用于在应用程序中实现多语言文本的加载与动态切换。它通过读取指定目录下的语言文件（如 `msg.txt`），将键值对形式的消息映射到目标语言，并提供线程安全的语言上下文管理。
|
||
|
||
---
|
||
|
||
## 模块依赖
|
||
|
||
```python
|
||
import os, re, sys
|
||
import codecs
|
||
from appPublic.folderUtils import _mkdir, ProgramPath
|
||
from appPublic.Singleton import SingletonDecorator
|
||
from appPublic.jsonConfig import getConfig
|
||
import threading
|
||
import time
|
||
import locale
|
||
```
|
||
|
||
> 说明：该模块依赖于 `appPublic` 包中的若干实用工具类和函数，包括单例装饰器、配置读取、路径处理等。
|
||
|
||
---
|
||
|
||
## 全局变量与常量
|
||
|
||
### 正则表达式
|
||
|
||
- `comment_re`: 匹配以 `#` 开头的注释行。
|
||
```python
|
||
comment_re = re.compile(r'\s*#.*')
|
||
```
|
||
|
||
- `msg_re`: 匹配形如 `key : value` 的消息条目（允许前后空格）。
|
||
```python
|
||
msg_re = re.compile(r'\s*([^:]*)\s*:\s*([^\s].*)')
|
||
```
|
||
|
||
### 编码转换表
|
||
|
||
用于对特殊字符进行编码/解码，避免配置文件解析冲突：
|
||
|
||
```python
|
||
convert_pairs = {
|
||
':': '\\x3A',
|
||
'\n': '\\x0A',
|
||
'\r': '\\x0D',
|
||
}
|
||
```
|
||
|
||
| 原始字符 | 编码表示 |
|
||
|--------|---------|
|
||
| `:` | `\x3A` |
|
||
| `\n` | `\x0A` |
|
||
| `\r` | `\x0D` |
|
||
|
||
---
|
||
|
||
## 核心函数
|
||
|
||
### `dictModify(d, md)`
|
||
合并字典 `md` 到字典 `d`，仅当值不为 `None` 时更新。
|
||
|
||
**参数：**
|
||
- `d` (dict): 目标字典
|
||
- `md` (dict): 更新数据字典
|
||
|
||
**返回：**
|
||
- 修改后的 `d`
|
||
|
||
---
|
||
|
||
### `charEncode(s)`
|
||
对字符串中的特殊字符进行编码替换，防止解析错误。
|
||
|
||
**参数：**
|
||
- `s` (str): 待编码字符串
|
||
|
||
**逻辑：**
|
||
1. 将 `\` 替换为 `\\\\`
|
||
2. 对 `convert_pairs` 中定义的字符进行编码替换
|
||
|
||
**示例：**
|
||
```python
|
||
charEncode("hello:world\n")
|
||
# 输出: "hello\\x3Aworld\\x0A"
|
||
```
|
||
|
||
---
|
||
|
||
### `charDecode(s)`
|
||
反向解码由 `charEncode` 编码的字符串。
|
||
|
||
**参数：**
|
||
- `s` (str): 已编码字符串
|
||
|
||
**逻辑：**
|
||
1. 按照 `convert_pairs` 的逆序还原特殊字符
|
||
2. 将 `\\\\` 还原为 `\`
|
||
|
||
**示例：**
|
||
```python
|
||
charDecode("hello\\x3Aworld\\x0A")
|
||
# 输出: "hello:world\n"
|
||
```
|
||
|
||
---
|
||
|
||
### `getTextDictFromLines(lines)`
|
||
从文本行列表中解析出语言键值对字典。
|
||
|
||
**参数：**
|
||
- `lines` (list of str): 文件内容的每一行
|
||
|
||
**处理规则：**
|
||
- 忽略空行和以 `#` 开头的注释行
|
||
- 使用正则匹配 `key : value` 结构
|
||
- 对 key 和 value 分别调用 `charDecode` 解码
|
||
|
||
**返回：**
|
||
- dict: `{原始消息: 翻译文本}`
|
||
|
||
---
|
||
|
||
### `getFirstLang(lang)`
|
||
从浏览器或系统传入的逗号分隔语言优先级列表中提取首选语言。
|
||
|
||
**参数：**
|
||
- `lang` (str): 如 `"zh-CN,zh;q=0.9,en-US;q=0.8"`
|
||
|
||
**返回：**
|
||
- str: 第一个语言代码（如 `"zh-CN"`）
|
||
|
||
---
|
||
|
||
## 核心类：`MiniI18N`
|
||
|
||
使用 `@SingletonDecorator` 实现单例模式，确保全局唯一实例。
|
||
|
||
### 类定义
|
||
```python
|
||
@SingletonDecorator
|
||
class MiniI18N:
|
||
```
|
||
|
||
---
|
||
|
||
### 构造函数 `__init__(path, lang=None, coding='utf8')`
|
||
|
||
初始化 i18n 引擎。
|
||
|
||
**参数：**
|
||
- `path` (str): 应用根路径，语言资源位于 `{path}/i18n/`
|
||
- `lang` (str, optional): 默认语言（可选）
|
||
- `coding` (str): 文件编码，默认 `'utf8'`
|
||
|
||
**初始化行为：**
|
||
- 获取系统默认语言 `locale.getdefaultlocale()[0]`
|
||
- 初始化内部字典：
|
||
- `langTextDict`: 存储各语言的翻译字典
|
||
- `messages`: 所有出现过的原始消息集合
|
||
- `clientLangs`: 线程级别的语言上下文（含时间戳）
|
||
- 加载语言映射配置（来自 `getConfig().langMapping`）
|
||
- 调用 `setupMiniI18N()` 加载所有语言文件
|
||
|
||
---
|
||
|
||
### 方法列表
|
||
|
||
#### `setLangMapping(lang, path)`
|
||
设置语言别名映射，例如将 `"zh"` 映射到 `"zh_CN"`。
|
||
|
||
**用途：** 支持语言标签标准化。
|
||
|
||
```python
|
||
i18n.setLangMapping('zh', 'zh_CN')
|
||
```
|
||
|
||
#### `getLangMapping(lang)`
|
||
获取实际使用的语言目录名。若无映射，则返回原语言名。
|
||
|
||
#### `setTimeout(timeout=600)`
|
||
设置客户端语言上下文的有效期（单位：秒）。超时后自动清理过期记录。
|
||
|
||
#### `delClientLangs()`
|
||
清理 `clientLangs` 中超过 `timeout` 时间未访问的线程语言设置。
|
||
|
||
> 自动在 `getCurrentLang` 和 `setCurrentLang` 中触发。
|
||
|
||
#### `getLangDict(lang)`
|
||
获取指定语言的完整翻译字典。
|
||
|
||
会先通过 `getLangMapping` 解析真实语言名称。
|
||
|
||
#### `getLangText(msg, lang=None)`
|
||
根据当前或指定语言查找翻译文本。
|
||
|
||
- 若未找到对应翻译，返回原始 `msg`
|
||
- 支持 bytes 输入自动解码
|
||
|
||
#### `setupMiniI18N()`
|
||
扫描 `{self.path}/i18n/` 目录下所有子目录（视为语言目录），读取其中的 `msg.txt` 文件并构建翻译字典。
|
||
|
||
**结构要求：**
|
||
```
|
||
<i18n_root>/
|
||
└── en_US/
|
||
└── msg.txt
|
||
└── zh_CN/
|
||
└── msg.txt
|
||
```
|
||
|
||
每条记录格式：
|
||
```
|
||
hello world : Hello, World!
|
||
greeting : Welcome to our app.
|
||
# 这是注释
|
||
error_open : Failed to open file: %s
|
||
```
|
||
|
||
#### `setCurrentLang(lang)`
|
||
为当前线程设置语言环境，并记录时间戳。
|
||
|
||
**注意：** 基于线程 ID 存储，支持多线程独立语言上下文。
|
||
|
||
#### `getCurrentLang()`
|
||
获取当前线程的语言设置。若未设置，则抛出异常（需确保已调用 `setCurrentLang`）。
|
||
|
||
---
|
||
|
||
## 辅助函数
|
||
|
||
### `getI18N(path=None, coding='utf8')`
|
||
获取 `MiniI18N` 单例实例的便捷入口。
|
||
|
||
**参数：**
|
||
- `path`: 项目根路径（默认为 `ProgramPath()`）
|
||
- `coding`: 文件编码
|
||
|
||
**返回：**
|
||
- `MiniI18N` 实例
|
||
|
||
**示例：**
|
||
```python
|
||
i18n = getI18N()
|
||
print(i18n("hello world")) # 根据当前线程语言输出翻译
|
||
```
|
||
|
||
---
|
||
|
||
## 使用示例
|
||
|
||
### 1. 准备语言文件
|
||
|
||
创建 `./i18n/en_US/msg.txt`：
|
||
```
|
||
hello : Hello, World!
|
||
greeting : Welcome!
|
||
```
|
||
|
||
创建 `./i18n/zh_CN/msg.txt`：
|
||
```
|
||
hello : 你好，世界！
|
||
greeting : 欢迎！
|
||
```
|
||
|
||
### 2. 在代码中使用
|
||
|
||
```python
|
||
from your_module import getI18N
|
||
|
||
i18n = getI18N()
|
||
|
||
# 设置当前线程语言
|
||
i18n.setCurrentLang('zh_CN')
|
||
|
||
# 获取翻译
|
||
print(i18n('hello')) # 输出: 你好，世界！
|
||
print(i18n('greeting')) # 输出: 欢迎！
|
||
|
||
# 切换语言
|
||
i18n.setCurrentLang('en_US')
|
||
print(i18n('hello')) # 输出: Hello, World!
|
||
```
|
||
|
||
---
|
||
|
||
## 高级特性
|
||
|
||
### 语言映射配置（via JSON Config）
|
||
|
||
在 `config.json` 中添加：
|
||
```json
|
||
{
|
||
"langMapping": {
|
||
"zh": "zh_CN",
|
||
"en": "en_US"
|
||
}
|
||
}
|
||
```
|
||
|
||
这样即使请求 `zh`，也会自动加载 `zh_CN` 的翻译文件。
|
||
|
||
### 线程安全设计
|
||
|
||
- 每个线程可通过 `setCurrentLang/lang` 独立设置语言
|
||
- 使用 `threading.currentThread()` 作为键存储上下文
|
||
- 定期清理过期线程状态（防止内存泄漏）
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **文件编码必须一致**，默认为 UTF-8。
|
||
2. 键名中不能包含未转义的 `:`、`\n`、`\r` 等特殊字符（应使用编码形式）。
|
||
3. 推荐使用英文原始消息作为 key，便于维护。
|
||
4. `msg.txt` 文件建议按功能模块分类组织。
|
||
|
||
---
|
||
|
||
## TODO / 扩展建议
|
||
|
||
- 支持 `.po` 或 `.yaml` 格式导入
|
||
- 提供运行时动态添加翻译接口
|
||
- 添加缺失翻译日志记录机制（`missed_pt` 可扩展）
|
||
- Web 场景下结合 Cookie 或 Header 自动识别语言
|
||
|
||
---
|
||
```
|
||
|
||
> ✅ **版本信息**
|
||
> 作者：AutoDoc Generator
|
||
> 生成时间：2025-04-05
|
||
> 模块版本：v1.0（基于所提供代码分析） |