Flask-Babel 必须显式调用 init_app() 且确保 get_locale() 返回值与 translations/目录名严格一致，否则 gettext() 静默失效；模板中语言切换链接须用 url_for() 动态生成，pybabel 提取需正确配置 jinja2 解析器及路径。
Flask-Babel 初始化时必须显式调用 init_app()，否则 gettext() 会静默失效
很多开发者在创建 Flask 实例后直接初始化 Babel，却忘了把应用实例传进去。结果是所有 _() 或 gettext() 调用都返回原始字符串，控制台也不报错，极难排查。
正确做法是分离实例化与绑定：
from flask import Flask from flask_babel import Babel <p>app = Flask(<strong>name</strong>) app.config['BABEL_DEFAULT_LOCALE'] = 'zh' app.config['BABEL_SUPPORTED_LOCALES'] = ['en', 'zh', 'ja']</p><p>babel = Babel() # 先实例化，不传 app babel.init_app(app) # 再显式绑定
-
Babel()构造时不传app，避免提前依赖未配置完的实例 -
init_app()必须在app.config设置好语言相关键之后调用 - 若用工厂模式（
create_app()），init_app()一定要放在配置加载完成之后
语言切换路由必须用 url_for() 生成，硬编码 URL 会导致 locale 参数丢失
用户点击「English」后页面没变？大概率是跳转用了 /en/xxx 这类静态路径，而 Flask-Babel 的语言上下文靠请求路径前缀（如 /zh/）或 query 参数（如 ?lang=ja）触发，但前提是路由能识别并注入当前 locale。
推荐方案：用带 lang 参数的统一路由 + url_for() 动态生成：
立即学习“Python免费学习笔记（深入）”；
@app.route('/<lang>/')
def index(lang):
return render_template('index.html')
<p>@app.route('/set_lang/<lang>')
def set_lang(lang):
if lang in app.config['BABEL_SUPPORTED_LOCALES']:
resp = make_response(redirect(url_for('index', lang=lang)))
resp.set_cookie('preferred_lang', lang, max_age=31536000)
return resp
return redirect(url_for('index', lang=app.config['BABEL_DEFAULT_LOCALE']))
- 所有模板中语言切换链接必须写成
{{ url_for('set_lang', lang='en') }}，不能写死/set_lang/en - 如果用了 URL 前缀（如
/zh/about），需配合flask-babel的refresh()或自定义LocaleSelector解析路径 - cookie 存储首选语言可绕过每次手动传参，但要注意和
request.accept_languages的优先级顺序
pybabel extract 扫描不到模板里的 _()？检查 Jinja2 模板扩展名和提取配置
pybabel extract -F babel.cfg -k _ -o messages.pot . 运行后 messages.pot 为空，常见原因不是代码写错了，而是配置漏了。
babel.cfg 必须明确声明 Jinja2 模板后缀，并指定 jinja2 解析器：
[python: **.py]
[jinja2: **/templates/**.html]
encoding = utf-8
- 模板路径要写对，比如你的模板在
app/templates/，那就要写**/templates/**.html，不能只写**.html - 如果用
.j2后缀，得加一行[jinja2: **.j2] -
extract默认不递归扫描子目录，确保.是项目根目录，且templates/在其下 - Jinja2 中的
{{ _('Login') }}能被识别，但{% trans %}Login{% endtrans %}需额外加-k trans参数
翻译文件编译后仍显示原文？确认 get_locale() 返回值与 .po 文件名严格匹配
你已经跑过 pybabel init -i messages.pot -d translations -l zh、填了中文、又 pybabel compile -d translations，但页面还是英文——大概率是 get_locale() 返回了 zh_CN，而你的目录叫 translations/zh/。
Flask-Babel 查找翻译时，只认 translations/<locale>/LC_MESSAGES/messages.mo</locale> 中的 <locale></locale>，它必须和 get_locale() 返回值完全一致（包括大小写和下划线）：
@babel.localeselector
def get_locale():
# ❌ 错误：返回 'zh_CN' 但只有 zh/ 目录
# return request.accept_languages.best_match(['zh_CN', 'en'])
<pre class="brush:php;toolbar:false;"># ✅ 正确：保持和目录名一致
return request.args.get('lang') or \
request.cookies.get('preferred_lang') or \
request.accept_languages.best_match(app.config['BABEL_SUPPORTED_LOCALES'])
- 运行
pybabel init -l zh创建的是translations/zh/；若想用zh_Hans，就得init -l zh_Hans并确保get_locale()也返回该字符串 -
pybabel compile不报错不代表成功，检查translations/zh/LC_MESSAGES/messages.mo文件是否真实生成且非空 - 开发时可在
get_locale()里加print()确认实际返回值，比猜快得多
Flask i18n 最容易卡住的地方不在语法，而在 locale 标识符的传递链条断在哪一环：从请求进来，到 get_locale() 输出，再到目录名、文件名、编译结果，任意一处大小写或分隔符不一致，就退回英文。动手前先用 print() 把这个值链路打出来，比反复重编译高效得多。
