本文介绍一种兼容 Pygbag（Web）与本地桌面环境的跨平台语言检测方案：在 Emscripten（Web）下通过 platform.window.navigator.language 获取浏览器语言，在桌面端回退至 locale.getdefaultlocale()，并提供健壮的 fallback 机制与实际集成示例。
本文介绍一种兼容 pygbag（web）与本地桌面环境的跨平台语言检测方案：在 emscripten（web）下通过 `platform.window.navigator.language` 获取浏览器语言，在桌面端回退至 `locale.getdefaultlocale()`，并提供健壮的 fallback 机制与实际集成示例。
在使用 Pygbag 将 Pygame 应用部署到 Web 环境时，传统依赖操作系统的语言探测方法（如 locale.getdefaultlocale()）会失效——因为 Emscripten 运行时无完整 POSIX locale 环境，返回值常为 ('C', 'ASCII') 或 None。而浏览器本身始终暴露标准的 navigator.language（如 'zh-CN'、'fr-FR'、'ja'），可通过 JavaScript API 安全访问。
Pygbag 提供了对浏览器全局对象的 Python 绑定：当 sys.platform == 'emscripten' 时，platform.window 即为 JS window 对象的代理，可直接链式调用 navigator.language。结合桌面端逻辑，我们可构建统一、健壮的语言自动识别函数：
import sys
import locale
import os
def get_language_code() -> str:
"""返回标准化的语言代码（如 'en_US', 'zh_CN', 'fr_FR'），优先使用浏览器语言（Web），回退系统 locale（Desktop）"""
if sys.platform == "emscripten":
# Web 环境：从浏览器 navigator 获取
try:
import platform
lang = platform.window.navigator.language or platform.window.navigator.userLanguage
# 标准化格式：将 'zh-CN' → 'zh_CN'，'en' → 'en_US'
if "-" in lang:
lang = lang.replace("-", "_")
elif len(lang) == 2: # 如 'en', 'de' → 补充默认区域
lang += "_US" if lang == "en" else f"_{lang.upper()}"
return lang
except (AttributeError, ImportError):
pass # Fallback to default
else:
# 桌面环境：使用系统 locale
try:
lang, _ = locale.getdefaultlocale()
if lang:
return lang
except:
pass
return "en_US" # 全局兜底
# 使用示例：加载对应语言的 JSON 字符串资源
STRDIR = "assets/locales"
def load_localized_strings() -> dict:
lang_code = get_language_code()
json_path = os.path.join(STRDIR, f"{lang_code}.json")
if os.path.exists(json_path):
import json
with open(json_path, "r", encoding="utf-8") as f:
return json.load(f)
# 尝试降级匹配（如 zh_CN → zh）
base_lang = lang_code.split("_")[0]
fallback_path = os.path.join(STRDIR, f"{base_lang}.json")
if os.path.exists(fallback_path):
import json
with open(fallback_path, "r", encoding="utf-8") as f:
return json.load(f)
# 最终回退到英文
with open(os.path.join(STRDIR, "en_US.json"), "r", encoding="utf-8") as f:
return json.load(f)关键注意事项：
- ✅ 必须在 sys.platform == 'emscripten' 分支中导入 platform：该模块仅在 Web 环境可用，桌面端导入会失败；
- ✅ navigator.language 是标准 Web API，兼容所有现代浏览器，无需额外权限；
- ⚠️ 避免硬编码 en_US 作为唯一 fallback：建议实现“语言族降级”（如 zh_CN → zh → en_US），提升多区域用户覆盖；
- ? 资源文件命名需统一：推荐全部使用 _ 分隔（zh_CN.json），而非 -，以匹配 Python locale 格式习惯；
- ? 无需修改 index.html：本方案完全在 Python 层实现，无需手动注入 URL 参数或 JS 变量，开箱即用。
该方案已在多个 Pygbag 游戏项目中稳定运行，兼顾简洁性、可维护性与跨平台一致性，是国际化 Pygame 应用的推荐实践。
