国际化（多语言）支持

语言: English | 中文

本文档说明如何在 OpenSynaptic 中使用和扩展多语言支持。

---

概述

OpenSynaptic 包含一个完整的国际化（i18n）系统，支持在应用代码和文档中使用多种语言。

支持的语言

• English (英文) - 原始语言
• 简体中文 (Chinese) - 中文翻译

---

快速开始

设置语言

from opensynaptic.utils import set_language, Language

# 使用枚举
set_language(Language.ZH)  # 中文

# 使用语言代码
from opensynaptic.utils import set_language_by_code
set_language_by_code('en')  # 英文

翻译消息

from opensynaptic.utils import translate
from opensynaptic.utils.constants import MESSAGES, LogMsg

# 获取当前语言的消息
msg = translate(MESSAGES[LogMsg.READY])

# 带参数的消息
msg = translate("Device {device_id} initialized", device_id="DEV-001")

集成到日志系统

日志系统会根据当前语言自动翻译消息：

from opensynaptic.utils import os_log

os_log.log_with_const(LogMsg.READY)  # 自动翻译为当前语言

---

架构

文件结构

src/opensynaptic/utils/
├── i18n.py                    # 核心 i18n 模块
│   ├── Language 枚举          # EN, ZH
│   ├── MESSAGES_EN            # 英文翻译
│   ├── MESSAGES_ZH            # 中文翻译
│   └── Translator 类          # 翻译引擎
├── constants.py               # 日志消息模板
└── logger.py                  # 集成翻译的日志系统

工作流程

应用代码
    ↓ 调用 translate()
i18n.Translator
    ↓ 查询当前语言
当前语言字典 (MESSAGES_EN 或 MESSAGES_ZH)
    ↓ 模板查询
翻译文本
    ↓ format() 参数替换
最终消息

---

API 参考

函数

set_language(lang: Language) → None

设置全局活跃语言。

from opensynaptic.utils import set_language, Language
set_language(Language.ZH)  # 设置中文

set_language_by_code(code: str) → None

通过语言代码设置活跃语言。大小写不敏感。

from opensynaptic.utils import set_language_by_code
set_language_by_code('zh')    # 中文
set_language_by_code('ZH')    # 相同
set_language_by_code('en')    # 英文
set_language_by_code('invalid')  # 默认为英文

get_current_language() → Language

获取当前活跃语言。

from opensynaptic.utils import get_current_language
current = get_current_language()
print(current)  # Language.ZH 或 Language.EN

translate(message: str, **kwargs) → str

翻译消息字符串。支持参数替换。

from opensynaptic.utils import translate

# 简单翻译
msg = translate("Initialization complete")

# 带参数的翻译
msg = translate("Device {id} is {status}", id="TEMP-01", status="online")

类

Translator

管理语言状态和翻译的核心类。

from opensynaptic.utils.i18n import Translator

translator = Translator()
translator.set_language('ZH')
translated = translator.translate("Hello")

---

添加新语言

步骤 1：更新枚举

在 src/opensynaptic/utils/i18n.py 中的 Language 枚举中添加新语言：

class Language(Enum):
    EN = "en"
    ZH = "zh"
    ES = "es"  # 新语言：西班牙语

步骤 2：添加翻译字典

MESSAGES_ES = {
    "Device initialized": "Dispositivo inicializado",
    "Ready for transmission": "Listo para transmisión",
    # ... 更多消息
}

步骤 3：注册到 Translator

# 在 Translator.__init__ 中
self.messages = {
    Language.EN: MESSAGES_EN,
    Language.ZH: MESSAGES_ZH,
    Language.ES: MESSAGES_ES,  # 新添加
}

步骤 4：导出到 init.py

# 在 src/opensynaptic/utils/__init__.py 中添加新检查（如果需要）
from opensynaptic.utils.i18n import Language  # 自动包含新值

---

环境变量

变量	说明	示例
OPENSYNAPTIC_LANG	初始化语言	OPENSYNAPTIC_LANG=zh

在应用启动时读取此变量：

import os
from opensynaptic.utils import set_language_by_code

initial_lang = os.getenv('OPENSYNAPTIC_LANG', 'en')
set_language_by_code(initial_lang)

---

配置集成

可以在 Config.json 中设置默认语言：

{
  "display_settings": {
    "language": "zh"
  }
}

应用启动时读取此设置：

from opensynaptic.core import OpenSynaptic
from opensynaptic.utils import set_language_by_code

node = OpenSynaptic()
lang = node.config.get('display_settings', {}).get('language', 'en')
set_language_by_code(lang)

---

示例：完整的多语言应用

from opensynaptic.core import OpenSynaptic
from opensynaptic.utils import set_language, Language, translate, os_log

# 初始化应用
def main():
    # 设置语言
    lang = input("Choose language (en/zh): ").strip().lower()
    set_language_by_code(lang)
    
    # 初始化节点
    node = OpenSynaptic()
    os_log.info(translate("Initializing system"))
    
    # 确保获得 ID
    if node.ensure_id("192.168.1.100", 8080):
        msg = translate("Device {id} assigned", id=node.assigned_id)
        os_log.info(msg)
    
    # 传输数据
    sensors = [["temp", "OK", 25.0, "degC"]]
    packet, aid, strategy = node.transmit(sensors=sensors)
    
    msg = translate("Packet sent: {size} bytes, strategy: {strat}",
                   size=len(packet), strat=strategy)
    os_log.info(msg)

if __name__ == "__main__":
    main()

---

测试多语言功能

# 运行 i18n 演示脚本
python scripts/demo_i18n.py

# 输出（示例）：
# ========== Demo: Basic Translation ==========
# English: Ready for transmission
# Chinese: 准备传输
# 
# ========== Demo: Logger Integration ==========
# [INFO] [英文] Ready for transmission
# [INFO] [中文] 准备传输

---

常见问题

Q: 如何为特定用户设置语言？

A: 在用户会话初始化时调用 set_language_by_code(user_lang)。由于语言是全局状态，这对该进程中的所有后续调用生效。

Q: 缺少的消息会怎样？

A: 如果消息未在当前语言字典中找到，Translator.translate() 返回原始消息字符串。

Q: 是否支持以 RTL（从右到左）语言？

A: 核心库支持任何语言，但 UI 布局需要特定改适。详见文档的 UI 部分。

---

更新消息翻译

当添加新消息或更新现有消息时：

1. 在 i18n.py 中的 MESSAGES_EN 中添加/更改英文消息
2. 在 MESSAGES_ZH 中添加对应的中文翻译
3. 保持键值完全一致
4. 测试所有语言的输出

---

语言: English | 中文
最后更新: 2026-04-04