FastAPI 多语言国际化实现：支持25种语言的博客系统

在全球化的今天，让网站支持多种语言已经成为一个基本需求。本文将详细介绍如何在 FastAPI 框架中实现一个完整的多语言支持系统，基于一个支持25种语言的博客项目实践。

功能特点

支持25种语言，覆盖全球主要语言
灵活的语言切换机制
多级语言选择优先级
基于 gettext 的翻译系统
高性能缓存优化
优雅的中间件实现

核心实现

1. 支持的语言配置

SUPPORTED_LANGUAGES = {
    'en': 'English',
    'zh': '中文',
    'vi': 'Tiếng Việt',     # 越南语
    'th': 'ไทย',           # 泰语
    'id': 'Bahasa Indonesia', # 印尼语
    'ms': 'Bahasa Melayu',   # 马来语
    'tl': 'Tagalog',         # 菲律宾语
    'my': 'မြန်မာစာ',         # 缅甸语
    'lo': 'ພາສາລາວ',         # 老挝语
    'km': 'ភាសាខ្មែរ',         # 柬埔寨语
    'ru': 'Русский',         # 俄语
    'fr': 'Français',        # 法语
    'it': 'Italiano',        # 意大利语
    'ja': '日本語',           # 日语
    'ko': '한국어',           # 韩语
    'de': 'Deutsch',         # 德语
    'ar': 'العربية',         # 阿拉伯语
    # 非洲语言支持
    'sw': 'Kiswahili',       # 斯瓦希里语
    'ha': 'Hausa',           # 豪萨语
    'am': 'አማርኛ',            # 阿姆哈拉语
    'yo': 'Yorùbá',          # 约鲁巴语
    'zu': 'isiZulu',         # 祖鲁语
    'xh': 'isiXhosa',        # 科萨语
}

2. 翻译器实现

使用 Python 的 gettext 模块实现翻译功能，并使用 lru_cache 进行性能优化：

@lru_cache(maxsize=None)
def get_translator(locale: str):
    return gettext.translation(
        'messages',
        localedir=os.path.join(os.path.dirname(__file__), 'locales'),
        languages=[locale],
        fallback=True
    )

3. 语言选择优先级机制

实现了一个三级优先级的语言选择机制：

def get_locale_from_request(request: Request) -> str:
    # 优先级：1.查询参数 2.cookie 3.header
    locale = (
        request.query_params.get('lang') or 
        request.cookies.get('locale') or 
        request.headers.get('accept-language', 'en')[:2]
    )
    if locale not in SUPPORTED_LANGUAGES:
        locale = 'en'  # 默认使用英语
    return locale

4. FastAPI 中间件集成

通过中间件将翻译功能无缝集成到 FastAPI 应用中：

def i18n_middleware(get_locale: Callable[[Request], str]):
    async def middleware(request: Request, call_next):
        locale = get_locale(request)
        translator = get_translator(locale)
        request.state.locale = locale
        request.state.gettext = translator.gettext
        request.state.supported_languages = SUPPORTED_LANGUAGES
        response = await call_next(request)
        return response
    return middleware

5. 前端语言选择器实现

使用 Bootstrap 实现优雅的语言选择下拉菜单：

<li class="nav-item dropdown">
    <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown">
        <i class="bi bi-globe"></i> {{ request.state.locale|upper }}
    </a>
    <ul class="dropdown-menu dropdown-menu-end">
        {% for lang_code, lang_name in supported_languages.items() %}
        <li>
            <a class="dropdown-item {% if request.state.locale == lang_code %}active{% endif %}" 
               href="#" 
               onclick="changeLanguage('{{ lang_code }}'); return false;">
                {{ lang_name }}
            </a>
        </li>
        {% endfor %}
    </ul>
</li>

翻译文件组织

项目使用标准的 gettext 翻译文件结构：

blog/
├── locales/
│   ├── en/
│   │   └── LC_MESSAGES/
│   │       ├── messages.po
│   │       └── messages.mo
│   ├── zh/
│   │   └── LC_MESSAGES/
│   │       ├── messages.po
│   │       └── messages.mo
│   └── ...（其他语言）

使用方法

在模板中使用翻译：

<h1>{{ gettext("Welcome to our blog") }}</h1>

在 Python 代码中使用翻译：

from fastapi import Request

def some_route(request: Request):
    translated_text = request.state.gettext("Welcome to our blog")
    return {"message": translated_text}

切换语言：
- 通过 URL 参数：?lang=zh
- 通过 Cookie：locale=zh
- 或通过浏览器的 Accept-Language header

性能优化

使用 @lru_cache 缓存翻译器实例
避免重复加载翻译文件
中间件中高效处理语言切换

扩展建议

添加新语言支持：
- 在 SUPPORTED_LANGUAGES 中添加新语言
- 创建对应的翻译文件
- 使用 pybabel 工具提取和更新翻译
改进语言检测：
- 添加地理位置检测
- 实现更智能的语言推荐
- 添加用户语言偏好存储
性能优化：
- 实现翻译文件的预编译
- 添加翻译缓存层
- 实现异步翻译加载

AI 辅助翻译实现

在多语言支持中，一个重要的挑战是如何高效地完成大量文本的翻译工作。我们可以借助人工智能技术来提高翻译效率和质量。

1. AI 翻译工具集成

可以集成多种 AI 翻译服务：

OpenAI GPT API
- 优势：上下文理解能力强，翻译更自然
- 适用：复杂句子、专业术语的翻译
Google Cloud Translation API
- 优势：支持语言广泛，速度快
- 适用：大量基础文本的快速翻译
Azure Translator
- 优势：企业级可靠性，多领域适配
- 适用：商业网站的专业翻译

2. 自动化翻译流程

async def ai_translate(text: str, target_lang: str) -> str:
    """
    使用 AI 进行翻译
    Args:
        text: 待翻译文本
        target_lang: 目标语言代码
    Returns:
        str: 翻译后的文本
    """
    try:
        # 根据文本长度和类型选择最适合的 AI 服务
        if len(text) > 1000 or is_technical_content(text):
            return await translate_with_gpt(text, target_lang)
        return await translate_with_google(text, target_lang)
    except Exception as e:
        logger.error(f"Translation failed: {e}")
        return text  # 翻译失败时返回原文

3. 翻译质量保证

上下文感知翻译

async def context_aware_translate(text: str, context: dict) -> str:
    """
    考虑上下文的 AI 翻译
    Args:
        text: 待翻译文本
        context: 上下文信息（如页面类型、专业领域等）
    """
    prompt = f"Context: {context['type']}, Domain: {context['domain']}\n{text}"
    return await ai_translate(prompt)

人工审核机制
- 设置翻译可信度阈值
- 对低可信度的翻译进行人工审核
- 建立翻译记忆库，提高翻译一致性

4. 性能优化

批量翻译处理

async def batch_translate(texts: List[str]) -> List[str]:
    """批量翻译以提高效率"""
    chunks = [texts[i:i+100] for i in range(0, len(texts), 100)]
    results = []
    for chunk in chunks:
        translations = await asyncio.gather(
            *[ai_translate(text) for text in chunk]
        )
        results.extend(translations)
    return results

翻译缓存

@cache.cached(timeout=3600)
async def cached_translate(text: str, target_lang: str) -> str:
    """缓存常用翻译结果"""
    return await ai_translate(text, target_lang)