React i18next在Django构建部署后无法加载translation.json文件

API 探路者

2026-8-28

问题根因

这是Django生产环境静态路由匹配优先级错误导致的：/locales/路径下的JSON翻译文件没有被静态资源规则匹配到，所有未命中后端接口、静态资源规则的请求都被兜底转发到了React入口index.html，才会出现200状态码但返回HTML内容、Content-Type为text/html的现象。
开发环境下React由自带的dev server启动，dev server默认会正确映射public目录下的locales资源路径，所以开发阶段多语言功能完全正常；build后将产物交由Django托管时，路由规则没有覆盖locales目录的资源响应逻辑，就会触发这个问题。

修复方案

按以下步骤逐一调整即可：

确认静态资源存放位置
将React项目public目录下的整个locales文件夹，完整拷贝到Django托管的前端build产物根目录，或者拷贝到Django配置的STATIC_ROOT目录下，保证文件权限和同目录下的js、css等静态资源一致。

调整Django路由匹配优先级
路由规则必须按「后端接口 > 静态资源匹配 > 前端兜底路由」的顺序配置，不能让/locales/开头的请求落到前端index.html兜底规则上。
如果是用Django自带的serve方法托管静态资源，可参考如下urls.py配置：

from django.urls import re_path
from django.views.static import serve
from django.conf import settings
import os

FRONTEND_BUILD_DIR = os.path.join(settings.BASE_DIR, 'build')

urlpatterns = [
    # 原有后端业务接口路由放在最前
    
    # 单独匹配locales翻译文件请求，优先级高于前端兜底
    re_path(
        r'^locales/(?P<path>.*)$',
        serve,
        {'document_root': os.path.join(FRONTEND_BUILD_DIR, 'locales')}
    ),
    # 匹配其他静态资源（js、css、图片等）
    re_path(
        r'^static/(?P<path>.*)$',
        serve,
        {'document_root': settings.STATIC_ROOT}
    ),
    # 最后配置前端路由兜底，所有未匹配的路径返回index.html
    re_path(
        r'^.*$',
        serve,
        {'document_root': FRONTEND_BUILD_DIR, 'path': 'index.html'}
    )
]

按需调整i18n加载路径
如果选择把locales文件夹放到STATIC目录下统一托管，需要同步修改i18n.js里的http-backend配置，把loadPath改成静态资源对应路径：

import i18n from 'i18next';
import Backend from 'i18next-http-backend';
import LanguageDetector from 'i18next-browser-languagedetector';
import { initReactI18next } from 'react-i18next';

i18n
  .use(Backend)
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    fallbackLng: 'en',
    supportedLngs: ['en', 'fr', 'ar'],
    debug: process.env.NODE_ENV === 'development',
    interpolation: {
      escapeValue: false,
    },
    backend: {
      loadPath: '/static/locales/{{lng}}/{{ns}}.json',
    }
  });

export default i18n;

生产环境用Nginx托管的额外说明
如果生产环境是Nginx负责静态资源响应、Django只处理接口请求，不需要修改Django路由，直接在Nginx配置中新增locales路径的匹配规则即可，同样要保证这条规则的优先级高于前端兜底路由：
```
location /locales/ {
  alias /path/to/your/frontend/build/locales/;
  expires 7d;
}

# 原有静态资源规则
location /static/ {
  alias /path/to/your/static/root/;
}

# 前端兜底路由放在最后
location / {
  try_files $uri $uri/ /index.html;
}
```
验证修复
重启对应服务（Django/Nginx），清空浏览器缓存后直接访问翻译文件地址，确认响应头Content-Type为application/json、响应内容为正确的翻译JSON对象，再测试语言切换功能即可恢复正常。

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