Django国际化需显式标记字符串:Python中用gettext_lazy(模型字段)或_(),模板中先{% load i18n %}再用{% trans %}或{% blocktrans %};漏标记、未运行makemessages或LocaleMiddleware位置错误均导致不生效。

Django 的国际化(i18n)和本地化(l10n)不是开箱即用的“自动翻译”,而是靠明确的标记 + 编译流程 + 语言环境切换来驱动,漏掉 makemessages 或没启用 LocaleMiddleware 就一定不生效。
如何正确标记待翻译的字符串
Django 不会扫描所有字符串,只识别被显式包裹的文本。核心是用 gettext 及其快捷方式(如 _)包裹,且必须在 Python 代码或模板中按规范写。
- Python 文件中:先
from django.utils.translation import gettext as _,再用_("Hello");带参数用gettext_lazy(如模型字段名、表单 label),否则迁移时可能报错 - 模板中:加载
{% load i18n %},然后用{% trans "Save" %}或{% blocktrans %}{{ count }} result{% plural %}{{ count }} results{% endblocktrans %} - JavaScript 字符串需单独处理:用
django-js-i18n视图暴露 JSON 翻译包,前端调用gettext()(需额外配置JavaScriptCatalog) - 别用字符串拼接:
_("Hi") + name会破坏上下文,应改用_("Hi %(name)s") % {"name": name}或 f-string 配合gettext
为什么 makemessages 没生成 .po 文件或漏了字符串
常见原因不是命令错了,而是路径、配置或语法没对齐。
- 确保
LOCALE_PATHS在settings.py中已定义(如[BASE_DIR / "locale"]),且该目录存在 - 运行命令时必须在项目根目录(manage.py 所在处),执行
python manage.py makemessages -l zh_Hans -l en;加-a可刷新全部语言,但不会删除已删源字符串的条目 - 模板里漏了
{% load i18n %},或用了双大括号直接渲染未标记字符串({{ title }}不会进 .po,除非{{ title|translate }}且后端做了适配) - Python 文件未被
makemessages扫描到:检查settings.py中USE_I18N = True,且文件在 INSTALLED_APPS 列表内 app 的目录下
为什么页面语言没切换,或者 get_language() 总返回默认值
语言切换依赖中间件链和请求头/cookie/session 的协同,不是设个变量就行。
- 确认
MIDDLEWARE中有'django.middleware.locale.LocaleMiddleware',且位置必须在SessionMiddleware和CommonMiddleware之后(顺序错会导致语言检测失败) - 用户语言来源优先级:URL 前缀(如
/zh-hans/) > session > cookie > Accept-Language 请求头 >LANGUAGE_CODE默认值;若想用 cookie 控制,需调用django.views.i18n.set_language视图并提交 POST - 调试时用
print(get_language())检查当前激活语言,注意它返回的是内部 code(如zh-hans),不是浏览器 header 里的zh-CN—— Django 会自动映射,但映射表在django/conf/global_settings.py里,自定义语言需手动加LANGUAGES - 静态文件(CSS/JS)里的文字不会被自动翻译,得用 JS i18n 方案或服务端渲染占位符
编译后的 .mo 文件不生效的典型场景
compilemessages 生成的是二进制 .mo,但 Django 只在特定条件下读取它。
- 必须运行
python manage.py compilemessages(不是makemessages),且终端当前路径仍需是项目根目录 - 检查
.po文件编码是否为 UTF-8(含 BOM 会失败),以及msgfmt工具是否可用(Django 会尝试调用系统命令,Windows 用户常因没装 GNU gettext 而静默失败) - 开发时
DEBUG = True下修改 .po 后需重启服务器;生产环境建议用mod_wsgi的touch-reload或重启进程 - 如果用 Nginx 直接托管静态文件,记得排除
/locale/路径,避免把翻译文件暴露出去
最易被忽略的是:语言切换依赖 URL 路由配置 —— 如果没用 i18n_patterns 包裹 urlpatterns,那么 LocaleMiddleware 就无法从路径提取语言前缀,整个基于路径的语言路由就失效了。这点在多语言 SEO 场景下几乎是硬性要求。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











