必须设 USE_I18N = True 且 LocaleMiddleware 位置正确（SessionMiddleware 前、CommonMiddleware 后），LOCALE_PATHS 指向 locale 父目录，语言码用 zh-hans（非下划线/大写），改 .po 后须 run compilemessages。
必须开 USE_I18N = True，USE_L10N = False 更安全；LocaleMiddleware 位置错、LOCALE_PATHS 指向错、语言代码写成 zh_CN 或 zh_Hans——这三类错误占实际配置失败的 80% 以上。
LocaleMiddleware 为什么没生效？顺序和依赖项缺一不可
它不读取请求路径或参数，只从 session → cookie → Accept-Language 头按序探测语言。但前提是：它得能读到 session 和 cookie。
-
SessionMiddleware必须在它之前（否则 session 为空） -
CommonMiddleware必须在它之后（否则 URL 解析提前终止，中间件链中断） -
USE_I18N = True必须显式设置（Django 4.0+ 默认为True，但老项目或自定义 settings 常被关掉） - 如果用了
i18n_patterns包路由，未包进去的路径（如/api/、/static/）完全不触发语言检测
makemessages -l zh-hans 报错或生成空 .po 文件？语言代码和路径是关键
报 CommandError: Unknown language code "zh_Hans" 是最常见错误——Django 只认 BCP 47 格式：zh-hans（小写 + 连字符），不是下划线、不是大写、不是 zh_CN。
- 查合法语言码：
python manage.py makemessages --list，输出里显示的才是可用值 -
LOCALE_PATHS必须指向locale的**父目录**，比如os.path.join(BASE_DIR, 'locale')，而不是os.path.join(BASE_DIR, 'locale', 'zh-hans') - 运行前手动创建
locale/目录（Django 不自动建） - 确保模板中用了
{% load i18n %}，且翻译字符串包裹在{% translate %}或{% blocktrans %}内
Python 代码里翻译字符串怎么写才不会“固定成默认语言”？
模块加载时就翻译的字符串，在后续请求中永远不变——这是模型字段、序列化器、表单等静态定义场景最常见的坑。
立即学习“Python免费学习笔记（深入）”；
- 视图、模板中用
gettext（或别名_）没问题，因为每次请求都重新执行 - 模型字段
verbose_name、序列化器error_messages、表单label等必须用gettext_lazy，否则启动时就固化为LANGUAGE_CODE对应语言 - 别在
__init__.py或模块顶层直接调用_()，除非你明确要静态翻译
切换语言后页面没变？compilemessages 和 Cookie 同步常被忽略
修改 .po 文件后不运行 compilemessages，Django 仍加载旧的 .mo 编译文件；而前端切换时只发 GET 到 /i18n/setlang/，会直接 405 错误。
- 每次改完
.po，必须执行：python manage.py compilemessages -l zh-hans -
set_language视图只接受 POST，需用表单提交：<form action="{% url 'set_language' %}" method="post">，并带csrf_token和next字段 - 如果想支持 JS 直接切换，推荐用
response.set_cookie(key=settings.LANGUAGE_COOKIE_NAME, value='en')显式写 Cookie，比依赖 session 更可控
真正卡住人的地方，往往不是概念，而是 LOCALE_PATHS 少了个 os.path.join、makemessages 用了下划线、或者 LocaleMiddleware 被塞到了 SecurityMiddleware 后面却没意识到 session 还没初始化——这些细节不报错，但让整个流程静默失效。
