Django多语言配置与i18n实现方法

本文深入解析了Django多语言（i18n）配置的核心要点与常见陷阱，强调必须同时启用`USE_I18N=True`、`USE_L10N=True`并在中间件中正确放置`LocaleMiddleware`（位于`SessionMiddleware`和`CommonMiddleware`之后），三者缺一不可，否则`ugettext_lazy`等翻译函数将完全失效；文章还揭秘了`_()`不能用于字符串拼接的根本原因——延迟求值机制与语言环境未就绪的冲突，并给出安全替代方案；同时系统梳理了`makemessages`生成空`.po`文件的隐蔽原因（如路径未配置`LOCALE_PATHS`、模板未加载`i18n`标签、Unicode异常字符干扰等），以及`LANGUAGES`与`LANGUAGE_CODE`协同实现用户语言切换的关键逻辑——从请求头、URL前缀到手动激活的完整链路，帮你避开90%开发者踩过的坑，真正让翻译“活”起来。

怎么在Django里开启i18n支持并让翻译生效

必须改 settings.py 里的三个关键配置，缺一不可，否则 ugettext_lazy 不会触发翻译，页面永远显示源语言。

• USE_I18N = True：启用国际化基础支持（默认是 True，但显式写上更稳妥）
• USE_L10N = True：本地化格式（日期/数字等），虽然和翻译无关，但很多模板依赖它，不开启可能导致 {% trans %} 标签失效
• MIDDLEWARE 中确保有 'django.middleware.locale.LocaleMiddleware'，且位置要在 SessionMiddleware 和 CommonMiddleware 之后、ResponseMiddleware 之前

漏掉 LocaleMiddleware 是最常踩的坑——你加了 ugettext_lazy，也生成了 .po 文件，但页面就是不切换语言，大概率是它没加载。

为什么ugettext\_lazy不能用在普通字符串拼接里

ugettext_lazy 返回的是一个“延迟求值”的代理对象，不是真实字符串。一旦参与 + 或 f-string，就会立刻触发求值，但此时 Django 还没设置好当前语言环境，结果固定为默认语言（通常是英文）。

• ❌ 错误写法：name = _('Hello') + ' ' + _('World') 或 f"{_('Hello')} {_('World')}"
• ✅ 正确做法：用 gettext_lazy 包裹整个字符串，或用 gettext + str.format() / % 占位符
• 示例：from django.utils.translation import gettext_lazy as _; FULL_NAME = _('Hello {name}').format(name=_('World'))（注意：这里两个 _ 都是 gettext_lazy，因为 format 在模板渲染时才执行）

这个陷阱在 model 字段 verbose_name、表单 label 里特别容易中招——这些地方只能用 lazy 版本，但又忍不住想拼接。

manage.py makemessages 生成空.po文件或找不到字符串

常见原因不是命令错了，而是路径或语法没对上。Django 默认只扫描 templates/ 和 Python 源码，且要求字符串字面量必须是函数调用形式。

• 确保 LOCALE_PATHS 已配置，比如 LOCALE_PATHS = [BASE_DIR / 'locale']，否则 .po 文件会生成在项目根目录下，而 compilemessages 找不到
• makemessages 不识别变量赋值中的翻译，例如 msg = _('Login') 是有效的，但 msg = 'Login'; _('Login') 这种“孤立调用”会被忽略
• 模板里必须用 {% load i18n %}，然后用 {% trans "Login" %} 或 {% blocktrans %}Hello {{ name }}{% endblocktrans %}，直接写 {{ _('Login') }} 不会提取
• 如果用了自定义模板后端（如 Jinja2），makemessages 默认不处理，得加 --engine jinja2

还有一种情况：你的字符串里有中文引号、全角空格或不可见 Unicode 字符，makemessages 会静默跳过——用编辑器显示所有字符检查一遍最省事。

LANGUAGES和LANGUAGE\_CODE怎么配合才能让用户切语言

LANGUAGE_CODE 只是 fallback，默认语言；真正决定用户看到什么，靠的是请求头 Accept-Language、URL 前缀（如果开了 i18n_patterns）、或你自己存的 session / cookie。

• LANGUAGES 必须显式声明支持哪些语言，比如 LANGUAGES = [('en', 'English'), ('zh-hans', 'Chinese')]，否则即使用户发来 zh-hans，Django 也会回退到 LANGUAGE_CODE
• 要支持 URL 切语言（如 /zh-hans/login/），必须用 i18n_patterns 包裹 urlconf，并确保 LocaleMiddleware 已启用
• 手动切换语言时，别直接改 request.LANGUAGE_CODE —— 它是只读的。应该用 django.utils.translation.activate('zh-hans')，再把语言写进 session 或 cookie
• activate() 的副作用是全局影响后续的 _() 调用，所以必须在每次请求开始时调用，不能只在 view 里调一次就以为完事了

最容易被忽略的是：浏览器语言设置和 Django 支持的语言 code 必须严格匹配。比如用户设了 zh-CN，但你只写了 zh-hans，就不会命中——要么统一用 BCP 47 标准（推荐），要么在 LANGUAGES 里补全别名。

今天关于《Django多语言配置与i18n实现方法》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！