Django gettext中文翻译在Cloud Run生产环境失效问题

问题背景 #

使用Django 5.0.2 + python-gettext 5.0开发网站，Windows 11本地开发环境中文翻译正常，通过Docker部署到Cloud Run后出现异常：仅部分翻译生效且内容与配置不符，但将中文翻译文件放到德语目录下却能正常显示所有中文内容。

CI/CD本地化配置 #

# 5. Localization step to make messages
- name: gcr.io/google-appengine/exec-wrapper
  args:
    - "-i"
    - "$_GCR_HOSTNAME/$PROJECT_ID/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA"
    - "-s"
    - "${PROJECT_ID}:${_DEPLOY_REGION}:${_DB_INSTANCE}"
    - "-e"
    - "SETTINGS_NAME=${_SECRET_SETTINGS_NAME}"
    - "-e"
    - "DJANGO_SETTINGS_MODULE=lt3aelaw.settings.production"
    - "--"
    - "python"
    - "manage.py"
    - "makemessages"
    - "-l"
    - "zh_HAns"
  id: Localization make messages

# 5.1 Localization step to make messages for de
- name: gcr.io/google-appengine/exec-wrapper
  args:
    - "-i"
    - "$_GCR_HOSTNAME/$PROJECT_ID/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA"
    - "-s"
    - "${PROJECT_ID}:${_DEPLOY_REGION}:${_DB_INSTANCE}"
    - "-e"
    - "SETTINGS_NAME=${_SECRET_SETTINGS_NAME}"
    - "-e"
    - "DJANGO_SETTINGS_MODULE=lt3aelaw.settings.production"
    - "--"
    - "python"
    - "manage.py"
    - "makemessages"
    - "-l"
    - "de"
  id: Localization make messages for de

# 6. Localization step to compile messages
- name: gcr.io/google-appengine/exec-wrapper
  args:
    - "-i"
    - "$_GCR_HOSTNAME/$PROJECT_ID/$REPO_NAME/$_SERVICE_NAME:$COMMIT_SHA"
    - "-s"
    - "${PROJECT_ID}:${_DEPLOY_REGION}:${_DB_INSTANCE}"
    - "-e"
    - "SETTINGS_NAME=${_SECRET_SETTINGS_NAME}"
    - "-e"
    - "DJANGO_SETTINGS_MODULE=lt3aelaw.settings.production"
    - "--"
    - "python"
    - "manage.py"
    - "compilemessages"
  id: Localization compile messages

代码中翻译写法 #

from django.utils.translation import activate, gettext as _
def index(request):
    showcaseHeader = _('Please contact us to get a free quote.')
    return render(request, 'pages/index.html', {'showcaseHeader':showcaseHeader})

核心异常 #

• 本地http://127.0.0.1:8000/zh-hans/所有中文翻译正常显示
• Cloud Run上https://myproject.run.app/zh-hans/仅“Home”被翻译（且内容与po文件配置的“主页”不符，显示为“首页”），其余内容均为英文
• 将中文的django.po和django.mo文件放到德语de目录后，https://myproject.run.app/de/可正常显示所有中文翻译

排查与解决步骤 #

1. 统一语言代码格式与大小写

   • 问题本质：Linux环境（Cloud Run容器）对文件路径大小写敏感，而Windows环境不敏感。当前CI/CD用zh_HAns生成翻译目录，但URL使用zh-hans，导致Django无法匹配到正确的翻译文件。
   • 修正：将CI/CD中makemessages -l zh_HAns改为makemessages -l zh-hans，确保生成的翻译目录为locale/zh-hans/LC_MESSAGES/，与URL中的语言代码完全一致。

2. 验证翻译文件路径与编译结果

   • 在CI/CD的compilemessages步骤后添加目录检查命令，确认路径正确性：

     - "--"
     - "ls"
     - "-la"
     - "locale/"
     

   • 确保django.mo文件存在于locale/zh-hans/LC_MESSAGES/目录下，无大小写错误。

3. 修正Django语言配置

   • 在settings.py中明确指定语言代码映射，避免自动转换导致的匹配问题：

     LANGUAGES = [
         ('en', 'English'),
         ('zh-hans', '简体中文'),
         ('de', 'Deutsch'),
     ]
     LOCALE_PATHS = [
         os.path.join(BASE_DIR, 'locale'),
     ]
     

4. 确认CI/CD工作目录

   • 确保exec-wrapper执行编译命令时处于项目根目录，否则可能将.mo文件编译到错误路径，导致部署后无法加载。

5. 清理缓存并重新构建

   • 清除CI/CD缓存，重新生成翻译文件并编译；部署前删除Cloud Run的旧镜像缓存，确保新的翻译文件被正确部署。

验证方法 #

• 部署后访问/zh-hans/，检查所有翻译内容是否正常显示
• 若仍有问题，在视图中添加日志输出，查看Django实际加载的翻译文件路径：

  from django.utils.translation import get_language, gettext
  import logging
  
  logger = logging.getLogger(__name__)
  def index(request):
      logger.info(f"Current language: {get_language()}")
      logger.info(f"Loaded translation files: {gettext._catalog._files}")
      # 其余代码不变
  

内容的提问来源于stack exchange，提问作者Bing Li