NodeJS+Express+EJS项目中基于URL路径配置i18n语言切换不生效问题

当前代码不生效的核心原因 #

• 全局变量污染：代码中使用的localeTag是全局作用域变量，Express异步处理请求的并发场景下，这个变量会被不同请求的赋值覆盖，最终大概率回落到默认的英文值
• 中间件执行顺序错位：全局注册的app.use()中间件会在路由参数解析完成之前执行，这时候根本还没拿到:locale路径段的值，获取到的locale是无效的
• i18n调用方式错误：直接给全局i18n实例调用setLocale是无效的——i18n的初始化中间件会把翻译能力、locale配置全部绑定到当前请求的req对象上，修改全局实例的配置，不会影响单个请求的翻译结果，反而会引发全局配置串线的并发问题
• 路由设计冗余：如果把所有路由都套上:locale前缀，需要改动所有原有路由的路径定义，维护成本极高

可直接复用的实现代码 #

1. 调整i18n基础配置 #

const i18n = require('i18n')
i18n.configure({
    locales: ['en', 'fr'],
    directory: './locales',
    // 关闭原有的查询参数识别，避免和路径逻辑冲突
    queryParameter: false,
    // 兜底的默认语言
    defaultLocale: 'en'
})

2. 注册路径语言解析中间件 #

必须把这个中间件放在i18n.init之后、所有业务路由之前，核心作用是从路径中提取语言标识，绑定到当前请求上，同时剥离路径里的语言段，让原有路由不用做任何修改：

// 先加载i18n初始化中间件
app.use(i18n.init)

// 路径语言解析逻辑
app.use((req, res, next) => {
    // 拆分请求路径，提取第一段作为语言标识
    const pathSegments = req.path.split('/').filter(Boolean)
    const targetLocale = pathSegments[0]

    // 校验提取到的语言是否在支持的列表内
    if (i18n.getLocales().includes(targetLocale)) {
        // 重点：给当前请求的i18n实例设置语言，而非修改全局实例
        req.setLocale(targetLocale)
        // 剥离路径中的语言段，后续路由识别到的是去掉语言前缀的原路径
        req.url = pathSegments.length > 1 ? `/${pathSegments.slice(1).join('/')}` : '/'
    } else {
        // 路径未携带有效语言时，使用默认语言
        req.setLocale(i18n.getLocale())
    }
    next()
})

3. 原有业务路由无需做任何修改 #

不管用户访问/en/about、/fr/home这类带语言前缀的地址，经过中间件处理后都会被映射到原来定义的路由上，不需要给每个路由添加:locale参数：

// 原来的路由逻辑和路径完全保留，不需要调整
app.get('/', (req, res) => {
    // 模板里的__()翻译函数会自动匹配当前请求设置的语言
    res.render('index', { welcome: req.__('home.welcome') })
})

app.get('/about', (req, res) => {
    res.render('about', { title: req.__('about.pageTitle') })
})

常见踩坑提醒 #

• 绝对不要把和当前请求相关的locale值存在全局对象上，否则并发访问时一定会出现不同用户看到的语言串线的问题
• 静态资源路径（如/css/style.css、/js/app.js）因为不匹配支持的语言列表，会被自动跳过语言逻辑，不会影响静态资源的正常加载
• EJS模板中使用的__()翻译方法是i18n中间件自动注入到模板上下文的，只要请求的locale设置正确，模板翻译会自动生效，不需要手动传参

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