首页 > 脚本专栏 > python > python fastapi多语言国际化

python使用fastapi实现多语言国际化的操作指南

2025-02-21 09:44:13 作者：老大白菜

本文介绍了使用Python和FastAPI实现多语言国际化的操作指南,包括多语言架构技术栈、翻译管理、前端本地化、语言切换机制以及常见陷阱和最佳实践,需要的朋友可以参考下

多语言国际化实现指南

项目多语言架构

技术栈

翻译管理：SQLAlchemy
翻译生成：Babel & Baidu Translate API
前端本地化：Jinja2 国际化扩展
转换工具：OpenCC (简繁转换)

目录结构

web/
├── locales/                # 语言资源目录
│   ├── zh/                 # 中文（简体）
│   ├── cht/                # 中文（繁体）
│   ├── en/                 # 英文
│   └── ...                 # 其他语言
├── scripts/
│   └── generate_po.py      # 翻译文件生成脚本
└── utils/
    └── baidutran.py        # 百度翻译工具
    └── chinesetw.py  # 中文转换工具

翻译工作流

1. 翻译数据存储

数据库 translations 表结构：

msgid：原始文本（中文）
msgstr：翻译文本
lang_code：语言代码

2. 翻译生成脚本 generate_po.py

主要功能

从数据库获取原始翻译文本
使用百度翻译 API 自动翻译
生成 .po 文件
支持指定语言或全量生成

使用方法

# 生成所有语言翻译
python generate_po.py

# 生成特定语言翻译
python generate_po.py en

3. 前端本地化 Jinja2

模板使用

<!-- 使用 _() 函数进行文本本地化 -->
<span>{{ _('用户名') }}</span>

4. 语言切换机制

路由处理

@router.get("/change_language")
def change_language(request: Request, lang: str):
    # 设置语言 Cookie 或 Session
    request.session['lang'] = lang

HTML 本地化实现

1. 基本本地化语法

在 HTML 模板中，使用 {{ _('文本') }} 进行文本本地化。

示例：用户资料页面 profile.html

<div class="info-item">
    <span class="info-label"> {{ _('账号类型') }} :</span>
    <span>
        {{ _('管理员') if user.is_admin else _('普通用户') }}
    </span>
</div>
<div class="info-item">
    <span class="info-label"> {{ _('性别') }} :</span>
    <span>
        {{ _('男') if user.sex == '1' else _('女') if user.sex == '0' else user.sex}}
    </span>
</div>

2. 条件本地化

可以在条件语句中使用本地化函数，如上例所示。

3. 消息页面本地化 message.html

<form action="" method="">
    <div class="mb-3">
        <input type="hidden" name="id" id="id" value="0">
        <label for="content" class="form-label">{{ _('询价') }} </label>
        <textarea class="form-control" id="content" name="content" rows="3" required></textarea>
    </div>
    <button type="button" class="btn btn-primary">{{ _('提交') }} </button>
</form>

4. JavaScript 本地化

在 JavaScript 中，可以通过服务端渲染的方式传递本地化文本。

示例：消息页面 JS 本地化

$(function(){
    $('.btn-primary').on('click', function(e) {
        $.ajax({
            url:'/addcomment',
            type: 'POST',
            data: form.serialize(),
            success: function(data) {
                if (data.status === 'success') {
                    location.reload();
                } else {
                    // 使用服务端传递的本地化错误消息
                    errorDiv.text(data.message);
                }
            }
        });
    });
});

5. 本地化最佳实践

始终使用 _() 函数包裹需要翻译的文本
避免在 JavaScript 中硬编码文本
使用服务端渲染传递本地化文本
为复杂的文本提供上下文注释

6. 常见陷阱

不要本地化 URL、路径等技术性文本
注意保持 HTML 结构的一致性
考虑不同语言的文本长度变化

百度翻译工具

功能概述

baidu_translate() 是一个强大的翻译函数，提供以下核心功能：

调用百度翻译 API 进行文本翻译
支持多种语言互相转换
内置错误处理和安全机制

实现代码

def baidu_translate(query, from_lang='zh', to_lang='en'):
    """调用百度翻译API进行翻译"""
    # 安全检查：跳过特定类型的文本
    if re.match(r'^/?https?://.+\.(jpg|png|jpeg|gif|bmp|mp3|wav|ogg|mp4|avi|mov|wmv|flv|mkv)$', query):
        return query
    elif re.match(r'^\d{1,11}@[\w.-]{2,30}\.[\w.-]{2,10}$', query):
        return query
    
    # 生成百度翻译所需的签名
    salt = random.randint(32768, 65536)
    sign_str = f"{app_id}{query}{salt}{secret_key}"
    sign = hashlib.md5(sign_str.encode('utf-8')).hexdigest()
    
    # 调用翻译 API
    params = {
        'q': query,
        'from': from_lang,
        'to': to_lang,
        'appid': app_id,
        'salt': salt,
        'sign': sign
    }

使用场景

1. 基本翻译

# 中文翻译到英文
english_text = baidu_translate("国际婚姻网", from_lang='zh', to_lang='en')
# 结果: "International Marriage Network"

# 英文翻译到中文
chinese_text = baidu_translate("Hello World", from_lang='en', to_lang='zh')
# 结果: "你好，世界"

2. 多语言支持

# 支持多种语言转换
japanese_text = baidu_translate("你好", from_lang='zh', to_lang='jp')
french_text = baidu_translate("Hello", from_lang='en', to_lang='fra')

安全与性能特性

安全机制

输入验证：跳过文件路径、邮箱等特定格式文本
签名生成：防止未授权调用
错误处理：详细的错误码映射

错误码映射

error_map = {
    '52003': '未授权用户',
    '54000': '必填参数为空',
    '54001': '签名错误',
    '54003': '访问频率受限',
    '54004': '账户余额不足',
    '54005': '长query请求频繁',
    '58000': '客户端IP非法',
    '58001': '译文语言方向不支持'
}

配置与依赖

环境变量

# .env 文件配置
BAIDU_TRANS_APPID=your_app_id
BAIDU_TRANS_SECRET_KEY=your_secret_key
BAIDU_TRANS_HOST=https://fanyi-api.baidu.com/api/trans/vip/translate

依赖库

requests：发送 HTTP 请求
hashlib：生成 MD5 签名
python-dotenv：加载环境变量

最佳实践

缓存翻译结果：对于重复翻译，考虑使用缓存
限制翻译频率：避免超过 API 调用限制
处理长文本：分段翻译大段文本
备用翻译方案：准备替代翻译服务

注意事项

API 调用有频率和额度限制
翻译质量取决于百度翻译 API
敏感或专业文本需人工校对
保护 API 密钥安全

替代方案

Google Translate API
DeepL 翻译 API
本地翻译字典
人工翻译服务

中文转换工具

ChineseConverter 工具类

功能概述

ChineseConverter 是一个强大的中文文本转换工具，提供以下核心功能：

简体中文 ↔ 繁体中文互转
中文文本转拼音
多种拼音样式支持

实现代码

class ChineseConverter:
    def __init__(self):
        self.s2t = OpenCC('s2t')  # 简体到繁体
        self.t2s = OpenCC('t2s')  # 繁体到简体

    def to_traditional(self, text: str) -> str:
        """将简体中文转换为繁体中文"""
        return self.s2t.convert(text)

    def to_simplified(self, text: str) -> str:
        """将繁体中文转换为简体中文"""
        return self.t2s.convert(text)

    def to_pinyin(self, text: str, style=Style.NORMAL) -> list:
        """
        将中文转换为拼音
        支持多种拼音样式
        """
        return pinyin(text, style=style)

    def to_pinyin_str(self, text: str, separator=' ', style=Style.NORMAL) -> str:
        """将中文转换为拼音字符串"""
        py_list = self.to_pinyin(text, style=style)
        return separator.join([''.join(p) for p in py_list])

拼音样式选项

Style.NORMAL：普通风格，不带声调

converter.to_pinyin_str("国际婚姻网")
# 输出: guo ji hun yin wang

Style.TONE：带声调的拼音

converter.to_pinyin_str("国际婚姻网", style=Style.TONE)
# 输出: guó jì hūn yìn wǎng

Style.TONE2：数字声调

converter.to_pinyin_str("国际婚姻网", style=Style.TONE2)
# 输出: guo2 ji4 hun1 yin4 wang3

Style.FIRST_LETTER：首字母

converter.to_pinyin_str("国际婚姻网", style=Style.FIRST_LETTER, separator='')
# 输出: gjhyw

使用场景

1. 简繁转换

# 简体转繁体
traditional_text = converter.to_traditional("国际婚姻网")
# 结果: 國際婚姻網

# 繁体转简体
simplified_text = converter.to_simplified("國際婚姻網")
# 结果: 国际婚姻网

2. 拼音转换

# 获取带声调拼音
pinyin_with_tone = converter.to_pinyin_str("国际婚姻网", style=Style.TONE)
# 结果: guó jì hūn yìn wǎng

性能与依赖

依赖库：
- opencc：处理简繁转换
- pypinyin：处理拼音转换
性能特点：
- 轻量级转换
- 无需调用外部 API
- 转换速度快
- 内存占用低

最佳实践

全局单例模式

# 推荐创建全局转换器实例
converter = ChineseConverter()

避免重复创建转换器实例
选择合适的拼音样式
处理特殊字符和非中文文本

注意事项

部分生僻字可能转换不准确
不支持方言转换
仅支持简体和繁体中文

替代方案

对于大规模、高精度转换，考虑专业翻译服务
对于特定领域术语，建议人工校对

翻译数据模型

数据库表结构 translations

class Translation(Base):
    __tablename__ = 'translations'
    
    # 主键
    id = Column(Integer, primary_key=True, autoincrement=True)
    
    # 原始文本标识符
    msgid = Column(String(255), nullable=False)
    
    # 翻译后的文本
    msgstr = Column(String(255), nullable=False)
    
    # 语言代码
    lang_code = Column(String(10), nullable=False)
    
    # 创建时间戳
    created_at = Column(DateTime, server_default=func.now())
    
    # 最后更新时间戳
    updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())

    # 唯一约束：确保每个 msgid 在特定语言中只有一个翻译
    __table_args__ = (
        UniqueConstraint('msgid', 'lang_code', name='unique_translation'),
    )

字段详解

id：
- 主键，自增
- 唯一标识每条翻译记录
msgid：
- 原始文本标识符
- 通常为中文（源语言）文本
- 最大长度 255 字符
msgstr：
- 翻译后的文本
- 对应特定语言的翻译结果
- 最大长度 255 字符
lang_code：
- 语言代码（如 ‘zh’, ‘en’, ‘cht’）
- 标识翻译的目标语言
created_at：
- 记录创建时间
- 使用数据库服务器默认时间
updated_at：
- 最后更新时间
- 自动更新，记录翻译修改时间

唯一约束

UniqueConstraint('msgid', 'lang_code', name='unique_translation')
确保每个文本在特定语言中只有一个翻译
防止重复翻译和数据冗余

使用场景示例

# 创建新翻译
new_translation = Translation(
    msgid='用户名',
    msgstr='Username',
    lang_code='en'
)
db.add(new_translation)
db.commit()

# 查询特定语言翻译
english_translations = db.query(Translation).filter_by(lang_code='en').all()

最佳实践

保持 msgid 的一致性
及时更新 updated_at 时间戳
定期清理过时或无效的翻译记录
为长文本考虑使用 Text 类型而非 String

翻译管理最佳实践

1. 翻译质量控制

使用人工审核机制
建立翻译记录日志
定期更新翻译缓存

2. 性能优化

缓存翻译结果
异步翻译处理
限制单次翻译数量

扩展性建议

1. 支持更多语言

在 language_version 表中添加新语言
更新 generate_po.py 支持新语言

2. 人工翻译集成

开发人工翻译审核界面
允许管理员修改自动翻译结果

故障排查

常见问题

翻译 API 调用失败
- 检查网络连接
- 验证 API 配额
- 使用备用翻译服务
本地化显示异常
- 确认 .po 文件生成正确
- 检查语言环境设置
- 验证 Jinja2 本地化配置

PO 文件生成脚本 generate_po.py

脚本功能概述

generate_po.py 是一个自动化翻译文件生成工具，提供以下核心功能：

从数据库获取原始翻译文本
使用百度翻译 API 自动生成翻译
创建 .po 格式的本地化文件
支持全量或指定语言翻译

主要实现逻辑

def generate_translations(output_dir='locales', specific_lang=None):
    """
    生成翻译文件
    
    Args:
        output_dir (str): 输出目录
        specific_lang (str, optional): 指定语言代码
    """
    # 获取中文（简体）基础翻译
    zh_translations = generator.get_translations('zh')
    
    # 确定要生成的语言
    if specific_lang:
        other_langs = [specific_lang]
    else:
        other_langs = generator.get_available_languages()

    # 为每种语言生成翻译文件
    for lang_code in other_langs:
        # 创建语言目录
        lang_dir = os.path.join(output_dir, lang_code, 'LC_MESSAGES')
        os.makedirs(lang_dir, exist_ok=True)
        
        # 生成 .po 文件
        with open(os.path.join(lang_dir, 'messages.po'), 'w') as f:
            # 写入文件头
            # 写入翻译条目
            for zh_trans in zh_translations:
                # 使用百度翻译 API 翻译
                msgstr = baidu_translate(zh_trans['msgid'], from_lang='zh', to_lang=lang_code)
                
                # 写入翻译条目
                f.write(f'msgid "{zh_trans["msgid"]}"\n')
                f.write(f'msgstr "{msgstr}"\n')

### 语言提示保存在表里

DROP TABLE IF EXISTS translations;
CREATE TABLE translations (
id int NOT NULL AUTO_INCREMENT,
msgid varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
msgstr varchar(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
lang_code varchar(10) CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci NOT NULL,
created_at timestamp NULL DEFAULT CURRENT_TIMESTAMP,
updated_at timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
PRIMARY KEY (id) USING BTREE,
UNIQUE INDEX unique_translation(msgid ASC, lang_code ASC) USING BTREE
) ENGINE = InnoDB AUTO_INCREMENT = 32 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_general_ci ROW_FORMAT = Dynamic;

INSERT INTO translations VALUES (1, ‘首页', ‘首页', ‘zh', ‘2025-02-15 13:50:35', ‘2025-02-15 13:53:03');
INSERT INTO translations VALUES (2, ‘分类', ‘分类', ‘zh', ‘2025-02-15 13:50:35', ‘2025-02-15 13:53:03');
INSERT INTO translations VALUES (3, ‘标签', ‘标签', ‘zh', ‘2025-02-15 13:50:35', ‘2025-02-15 13:53:03');
INSERT INTO translations VALUES (4, ‘关于', ‘关于', ‘zh', ‘2025-02-15 13:50:35', ‘2025-02-15 13:53:03');
INSERT INTO translations VALUES (5, ‘个人资料', ‘个人资料', ‘zh', ‘2025-02-15 13:50:35', ‘2025-02-15 13:53:03');

#中文
msgid “邮件验证”
msgstr “邮件验证”

msgid “邮箱”
msgstr “邮箱”

msgid “邮编”
msgstr “邮编”

msgid “阅读更多”
msgstr “阅读更多”

msgid “首页”
msgstr “阅读更多”

msgid “验证码”
msgstr “验证码”
msgid “邮件验证”
msgstr “Email Verification”

msgid “邮箱”
msgstr “Email Box”

msgid “邮编”
msgstr “Postal Code”

msgid “阅读更多”
msgstr “Read More”

msgid “首页”
msgstr “Home Page”

msgid “验证码”
msgstr “Verification Code”

以上就是python使用fastapi实现多语言国际化的操作指南的详细内容，更多关于python fastapi多语言国际化的资料请关注脚本之家其它相关文章！

python使用fastapi实现多语言国际化的操作指南

多语言国际化实现指南

项目多语言架构

技术栈

目录结构

翻译工作流

1. 翻译数据存储

2. 翻译生成脚本 generate_po.py

3. 前端本地化 Jinja2

4. 语言切换机制

HTML 本地化实现

1. 基本本地化语法

2. 条件本地化

3. 消息页面本地化 message.html

4. JavaScript 本地化

5. 本地化最佳实践

6. 常见陷阱

百度翻译工具

功能概述

实现代码

使用场景

安全与性能特性

配置与依赖

最佳实践

注意事项

替代方案

中文转换工具

ChineseConverter 工具类

拼音样式选项

使用场景

性能与依赖

最佳实践

注意事项

替代方案

翻译数据模型

数据库表结构 translations

字段详解

唯一约束

使用场景示例

最佳实践

翻译管理最佳实践

1. 翻译质量控制

2. 性能优化

扩展性建议

1. 支持更多语言

2. 人工翻译集成

故障排查

常见问题

PO 文件生成脚本 generate_po.py

脚本功能概述

主要实现逻辑

您可能感兴趣的文章: