国际化

核心特性

SDK 提供完整的国际化解决方案，支持基于 .ini 文件的多语言配置，结合请求参数 lang 自动翻译响应信息和错误提示，让您的应用轻松支持全球化部署。

功能概览

• 灵活配置：基于 .ini 文件的语言配置，支持动态加载
• 自动翻译：框架自动识别语言环境，无需手动处理
• 参数化支持：支持占位符翻译，动态内容填充
• 表单验证集成：与表单验证系统深度集成，提供一致的错误提示
• 高性能：内置缓存机制，确保翻译性能

---

快速开始

目录结构配置

项目根目录下需包含 i18n/ 目录，存放多语言配置文件：

project/
├── main.py
├── i18n/
│   ├── zh-CN.ini    # 简体中文
│   ├── en.ini       # 英语
│   ├── zh-TW.ini    # 繁体中文（可选）
│   └── ja.ini       # 日语（可选）
└── requirements.txt

初始化配置

# main.py - 基础中间件示例
import asyncio
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify
from simplejrpc import RPCMiddleware

# 创建应用实例
app = ServerApplication(socket_path="app.socket", i18n_dir="./i18n")

@app.route(name="hello")
async def hello(name: str = "World"):
    """简单的问候接口"""
    return jsonify(
        data=f"Hello, {name}!", 
        msg="请求处理成功"
    )

if __name__ == "__main__":
    asyncio.run(app.run())

重要提醒

在进行服务的初始化的时候传入 i18n 国际化的目录，请确保目录路径存在。
每次请求必须传入 lang 参数，框架将自动识别并设置当前语言环境。如果未传入 lang 参数，将使用初始化时设置的默认语言。
框架默认使用 en 语言。

语言文件配置

基础翻译配置

创建语言配置文件，定义翻译键值对：

zh-CN.ini

# 基础状态信息
STATUS_OK = 操作成功
STATUS_FAILED = 操作失败
STATUS_UNAUTHORIZED = 未授权访问

# 业务相关
USER_NOT_FOUND = 用户不存在
INVALID_PASSWORD = 密码错误
TEST_I18N = 测试

en.ini

# Basic status messages
STATUS_OK = Operation successful
STATUS_FAILED = Operation failed
STATUS_UNAUTHORIZED = Unauthorized access

# Business related
USER_NOT_FOUND = User not found
INVALID_PASSWORD = Invalid password
TEST_I18N = Test

基础翻译使用

from simplejrpc.i18n import T as i18n

# 基础翻译，这个需要在正常的业务中去使用
print(i18n.translate("TEST_I18N"))        # 输出：测试
print(i18n.translate("STATUS_OK"))        # 输出：操作成功
print(i18n.translate("USER_NOT_FOUND"))   # 输出：用户不存在

---

参数化翻译

占位符配置

支持使用 {} 占位符进行动态内容填充：

zh-CN.ini

# 单个参数
WELCOME_USER = 欢迎，{}！
TEST_PARAM = 测试{}

# 多个参数
USER_LOGIN_SUCCESS = 用户 {} 于 {} 成功登录
FILE_UPLOAD_INFO = 文件 {} 上传成功，大小：{} KB
VALIDATION_RANGE = 值必须在 {} 到 {} 之间

en.ini

# Single parameter
WELCOME_USER = Welcome, {}!
TEST_PARAM = Test {}

# Multiple parameters
USER_LOGIN_SUCCESS = User {} logged in successfully at {}
FILE_UPLOAD_INFO = File {} uploaded successfully, size: {} KB
VALIDATION_RANGE = Value must be between {} and {}

参数化翻译使用

from simplejrpc.i18n import T as i18n

# 单个参数
print(i18n.translate_ctx("WELCOME_USER", "张三"))  
# 输出：欢迎，张三！

print(i18n.translate_ctx("TEST_PARAM", "国际化"))  
# 输出：测试国际化

# 多个参数
print(i18n.translate_ctx("USER_LOGIN_SUCCESS", "admin", "2024-01-15 10:30:00"))
# 输出：用户 admin 于 2024-01-15 10:30:00 成功登录

print(i18n.translate_ctx("VALIDATION_RANGE", "1", "100"))
# 输出：值必须在 1 到 100 之间

---

支持语言列表

标准语言代码

语言代码	语言名称	地区/备注	配置文件名	推荐使用场景
en	English	英语（国际通用）	en.ini	默认回退语言
zh-CN	简体中文	中国大陆	zh-CN.ini	中国市场
zh-TW	繁体中文	台湾、香港、澳门	zh-TW.ini	港澳台市场
ja	Japanese	日本	ja.ini	日本市场
ru	Russian	俄罗斯	ru.ini	俄语地区

---

开发最佳实践

命名规范建议

# 推荐的命名方式
# 1. 使用大写字母和下划线
STATUS_OK = 操作成功
ERROR_UNAUTHORIZED = 未授权访问
USER_NOT_FOUND = 用户不存在

# 2. 按功能模块分组
# 用户相关
USER_LOGIN_SUCCESS = 登录成功
USER_LOGOUT_SUCCESS = 退出成功
USER_PROFILE_UPDATED = 个人资料已更新

# 订单相关
ORDER_CREATED = 订单创建成功
ORDER_CANCELLED = 订单已取消
ORDER_PAYMENT_PENDING = 订单待支付

# 3. 使用语义化前缀
MSG_WELCOME = 欢迎使用
ERR_INVALID_INPUT = 输入无效
WARN_DATA_LOSS = 数据可能丢失
INFO_PROCESSING = 正在处理

同步管理策略

1. 键值一致性检查：确保所有语言文件包含相同的键
2. 翻译完整性验证：定期检查翻译缺失
3. 版本控制集成：将语言文件纳入版本控制
4. 自动化测试：编写测试用例验证翻译功能

---

实际应用示例

示例 1：基础接口国际化

创建支持多语言的基础接口：

# main.py
import asyncio
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify
from simplejrpc.i18n import T as i18n


app = ServerApplication(socket_path="app.socket",i18n_dir="i18n")

@app.route(name="hello")
async def hello(lang):
    """多语言问候接口"""
    greeting_msg = i18n.translate_ctx("GREETING_MESSAGE", "World")
    return jsonify(
        data=greeting_msg, 
        msg=i18n.translate("STATUS_OK")
    )

@app.route(name="user_info")
async def get_user_info(lang, user_id: int):
    """获取用户信息接口"""
    # 模拟用户数据
    user_data = {
        "id": user_id,
        "name": "张三",
        "status": "active"
    }
    
    success_msg = i18n.translate_ctx("USER_INFO_SUCCESS", user_data["name"])
    return jsonify(
        data=user_data,
        msg=success_msg
    )

if __name__ == "__main__":
    asyncio.run(app.run())

配置文件示例：

# zh-CN.ini
STATUS_OK = 操作成功
GREETING_MESSAGE = 你好，{}！
USER_INFO_SUCCESS = 成功获取用户 {} 的信息

# en.ini
STATUS_OK = Operation successful
GREETING_MESSAGE = Hello, {}!
USER_INFO_SUCCESS = Successfully retrieved information for user {}

响应示例（中文）：

{
  "jsonrpc": "2.0",
  "result": {
    "code": 200,
    "meta": {"endpoint": null, "close": 1},
    "data": "你好，World！",
    "msg": "操作成功"
  },
  "id": 1
}

---

示例 2：异常处理国际化

实现带有国际化错误提示的异常处理：

# main.py
import asyncio
import os
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify
from simplejrpc.i18n import T as i18n
from simplejrpc.exceptions import RPCException

app = ServerApplication(socket_path="app.socket",i18n_dir="i18n")

@app.route(name="get_config_info")
async def get_config_info(lang):
    """获取配置信息接口"""
    try:
        config_path = "config.ini"
        if not os.path.exists(config_path):
            raise FileNotFoundError(i18n.translate("CONFIG_FILE_NOT_FOUND"))
            
        with open(config_path, "r", encoding="utf-8") as f:
            data = f.read()
            
    except FileNotFoundError as e:
        # RPCException 必须是框架提供的异常类，否则无法进行捕获
        raise RPCException(i18n.translate("CONFIG_FILE_NOT_FOUND"))
    
    return jsonify(
        data={"config": data}, 
        msg=i18n.translate("CONFIG_READ_SUCCESS")
    )

if __name__ == "__main__":
    asyncio.run(app.run())

错误信息配置：

# zh-CN.ini
CONFIG_FILE_NOT_FOUND = 配置文件不存在

错误响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "code": 400,
    "meta": {"endpoint": null, "close": 1},
    "data": null,
    "msg": "配置文件不存在"
  },
  "id": 1
}

---

---

示例 3：表单验证国际化

在 simplejrpc 2.1.7+ 版本中，使用 TextMessage 可以精确控制表单验证的国际化行为：

基础用法示例：

# main.py
import asyncio
from simplejrpc import TextMessage
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify
from simplejrpc.i18n import GI18n, T as i18n
from simplejrpc import (
    BaseForm,
    RequireValidator,
    StringField
)

# 初始化国际化
app = ServerApplication(socket_path="app.socket",i18n_dir="i18n")

class UserRegistrationForm(BaseForm):
    """用户注册表单"""
    username = StringField(
        validators=[RequireValidator(
            TextMessage("PARAMETER_CANNOT_BE_EMPTY")
        )]
    )
    email = StringField(
        validators=[RequireValidator(
            TextMessage("PARAMETER_CANNOT_BE_EMPTY")
        )]
    )
    role = StringField(
        validators=[RequireValidator(
            TextMessage("PARAMETER_CANNOT_BE_EMPTY")
        )]
    )

@app.route(name="user_register", form=UserRegistrationForm)
async def user_register(lang, username, email, role):
    """用户注册接口"""
    # 模拟注册逻辑
    user_data = {
        "id": 12345,
        "username": username,
        "email": email,
        "role": role
    }
    
    return jsonify(
        data=user_data,
        msg=i18n.translate_ctx("USER_REGISTER_SUCCESS", username)
    )

if __name__ == "__main__":
    asyncio.run(app.run())

配置文件：

# zh-CN.ini
PARAMETER_CANNOT_BE_EMPTY = "参数不能为空"

# en.ini
PARAMETER_CANNOT_BE_EMPTY = "Parameters cannot be empty"

验证失败响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "code": 400,
    "meta": {"endpoint": null, "close": 1},
    "data": null,
    "msg": "参数不能为空"
  },
  "id": 1
}

---

重要提醒

• 不要在验证器中直接调用 i18n.translate()，可能因上下文未初始化而失败
• 使用 TextMessage 是更安全可靠的方式
• 确保所有语言文件都包含相应的翻译键

---

国际化自动加载

ServerApplication 支持自动查找国际化目录，提供灵活的路径指定方式：

from simplejrpc.app import ServerApplication

# 方式1：显式指定配置文件路径
app = ServerApplication(
    socket_path="app.socket",
    i18n_dir="i18n"  # 指定国际化目录路径
)

# 方式2：不指定路径，框架自动查找
app = ServerApplication(
    socket_path="app.socket"
    # 框架会自动在项目根目录查找 i18n 目录
)