Next.js中next-i18next配置missingKeyHandler遇序列化错误求助

问题根源 #

next-i18next的配置文件会在服务端和客户端之间共享并序列化，而missingKeyHandler是函数类型，无法被序列化为JSON，直接在next-i18next.config.js中添加会触发序列化错误。

解决方案 #

我们需要拆分服务端和客户端的处理逻辑，分别实现缺失key的捕获：

1. 基础配置调整

先修改next-i18next.config.js，只保留可序列化的配置项，开启saveMissing但不添加missingKeyHandler：

// next-i18next.config.js
module.exports = {
  i18n: {
    locales: ['en', 'zh'],
    defaultLocale: 'en',
    saveMissing: true, // 开启缺失key标记
  },
  // 不要在这里添加missingKeyHandler函数
}

2. 服务端添加missingKeyHandler

在服务端单独初始化i18next实例并配置missingKeyHandler，避免序列化问题。可以创建一个服务端专用的i18n初始化文件：

// utils/server-i18n.js
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import { defaultNS, resources } from '../public/locales' // 导入你的翻译资源
import backendApi from '../utils/backend-api' // 你的后端请求工具

i18n
  .use(initReactI18next)
  .init({
    resources,
    defaultNS,
    lng: 'en',
    saveMissing: true,
    missingKeyHandler: async (lng, ns, key, fallbackValue) => {
      // 调用后端接口存入数据库
      try {
        await backendApi.post('/api/save-missing-key', {
          lng,
          ns,
          key,
          fallbackValue,
        })
      } catch (err) {
        console.error('保存缺失翻译key失败:', err)
      }
    },
  })

export default i18n

在服务端代码（比如API路由、getServerSideProps、Server Components）中，导入并使用这个服务端i18n实例即可。

3. 客户端捕获缺失key

客户端无法直接在i18next配置中添加函数，我们可以扩展useTranslation钩子，在翻译时检查是否返回原始key（说明key缺失），再调用后端接口：

// utils/useEnhancedTranslation.js
import { useTranslation as useOriginalTranslation } from 'next-i18next'
import backendApi from './backend-api'

export const useTranslation = (ns, options) => {
  const { t, i18n } = useOriginalTranslation(ns, options)

  const enhancedT = (key, translationOptions) => {
    const translatedValue = t(key, translationOptions)
    // 判断是否key缺失（i18next默认返回key本身）
    if (translatedValue === key) {
      // 调用后端接口，可添加防抖逻辑避免重复请求
      backendApi.post('/api/save-missing-key', {
        lng: i18n.language,
        ns: ns || i18n.options.defaultNS,
        key,
        fallbackValue: translatedValue,
      }).catch(err => {
        console.error('客户端保存缺失翻译key失败:', err)
      })
    }
    return translatedValue
  }

  return { ...useOriginalTranslation(ns, options), t: enhancedT }
}

之后在客户端组件中，使用这个自定义的useTranslation钩子替代原生即可。

4. 后端接口实现

编写一个API路由接收缺失的key并存入数据库，比如pages/api/save-missing-key.js：

// pages/api/save-missing-key.js
import db from '../../utils/db' // 你的数据库连接

export default async function handler(req, res) {
  if (req.method !== 'POST') {
    return res.status(405).json({ message: 'Method not allowed' })
  }

  const { lng, ns, key, fallbackValue } = req.body

  try {
    // 存入数据库的逻辑，根据你的数据库类型调整
    await db.query(
      'INSERT INTO missing_translations (lng, ns, key, fallback_value) VALUES (?, ?, ?, ?) ON DUPLICATE KEY UPDATE updated_at = NOW()',
      [lng, ns, key, fallbackValue]
    )
    res.status(200).json({ message: '保存成功' })
  } catch (err) {
    console.error('数据库操作失败:', err)
    res.status(500).json({ message: '保存失败' })
  }
}

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