如何配置i18next实现翻译键大小写不敏感匹配

i18next默认对翻译键做大小写精确匹配，没有提供开箱即用的大小写不敏感开关，可通过以下两种方案实现需求：

方案一：资源预处理+包装t方法（性能最优，推荐） #

核心逻辑是初始化阶段统一将所有翻译资源的键转为小写存储，调用翻译方法时自动把传入的键也转为小写后再查找，全程无额外运行时遍历开销，适合翻译资源体量较大的项目。

• 先写一个递归转换对象键为小写的工具函数：

function convertKeysToLowerCase(target) {
  if (typeof target !== 'object' || target === null) return target
  return Object.keys(target).reduce((result, key) => {
    result[key.toLowerCase()] = convertKeysToLowerCase(target[key])
    return result
  }, {})
}

• 初始化i18next时，预处理所有导入的翻译资源：

import i18n from "i18next";
// 导入你的翻译文件
import faIR from './locales/fa.json';
import enUS from './locales/en.json';

const resources = {
  fa: { translation: convertKeysToLowerCase(faIR) },
  en: { translation: convertKeysToLowerCase(enUS) }
}

i18n.init({
  resources,
  lng: 'fa',
  interpolation: {
    escapeValue: false
  }
  // 其余原有配置保持不变
})

• 包装原生t方法，统一处理传入的键：

const originT = i18n.t.bind(i18n)
i18n.t = (key, options) => {
  const formatKey = typeof key === 'string' ? key.toLowerCase() : key
  return originT(formatKey, options)
}

方案二：自定义插件重写查找逻辑（侵入性最低） #

如果不想修改原有翻译资源、也不想包装原生t方法，可以写一个极简i18next插件，拦截资源查找流程：原始键匹配失败时，自动做大小写不敏感的二次匹配。该方案仅在原始键未命中时才会做遍历匹配，绝大多数业务场景下性能损耗可忽略。

const caseInsensitivePlugin = {
  type: 'i18nFormat',
  init(i18next) {
    const originGetResource = i18next.services.resourceStore.getResource.bind(i18next.services.resourceStore)
    i18next.services.resourceStore.getResource = function(lang, ns, key, opts) {
      // 先走原生精确匹配
      const matchResult = originGetResource(lang, ns, key, opts)
      if (matchResult !== undefined) return matchResult
      // 精确匹配失败时，遍历当前命名空间下的键做大小写不敏感匹配
      const nsData = i18next.services.resourceStore.data[lang]?.[ns]
      if (!nsData) return undefined
      const targetKey = Object.keys(nsData).find(item => item.toLowerCase() === key.toLowerCase())
      return targetKey ? originGetResource(lang, ns, targetKey, opts) : undefined
    }
  }
}

// 初始化时引入插件即可
i18n.use(caseInsensitivePlugin).init({
  // 原有配置完全不需要修改
})

效果验证 #

针对给出的示例场景，翻译文件中存在配置：

{
  "My Name": "نام من"
}

配置完成后，调用t('My Name')、t('my name')甚至t('MY NAME')，都能正确返回翻译结果نام من。

注意：如果项目使用了多层嵌套的翻译键，方案一的递归转换函数天然支持嵌套场景；方案二需要将单层遍历键的逻辑替换为递归遍历嵌套对象的逻辑，即可支持嵌套键的大小写不敏感匹配。

内容的提问来源于stack exchange，提问作者Mir-Ismaili