在Next-Intl项目中处理带点号的翻译键名问题

Next-Intl是一个流行的国际化库，用于Next.js应用的多语言支持。在实际开发中，开发者有时会遇到翻译键名中包含点号(.)的情况，这会导致库报错。本文将探讨这一问题的背景、原因以及解决方案。

问题背景

许多开发者习惯直接使用英文文本作为翻译键名，例如：

t('Welcome to the app')

这种方式相比使用抽象标识符(如home.welcome)更加直观，开发者可以直接在代码中看到最终显示的文本，而无需在代码和翻译文件之间来回切换。

然而，当文本中包含点号时，例如：

t('Welcome to the app. Go to your profile to update your information.')

Next-Intl会抛出错误，因为库默认将点号解析为路径分隔符，试图访问嵌套的翻译对象。

技术原因

Next-Intl设计上使用点号作为嵌套翻译键名的分隔符，这是许多国际化库的常见做法。例如：

{
  "home": {
    "welcome": "Welcome"
  }
}

可以通过t('home.welcome')访问。

当键名本身包含点号时，库会错误地尝试解析这些点号作为路径分隔符，导致查找失败。

解决方案

虽然官方不建议使用文本作为键名，但开发者可以通过以下方式解决点号问题：

1. 键名转换方案

在加载翻译文件时，将所有点号替换为其他字符(如下划线)：

const adjustKeys = (obj: Record<string, any>): Record<string, any> =>
  Object.fromEntries(
    Object.entries(obj).map(([key, value]) =>
      typeof value === 'string'
        ? [key.replaceAll('.', '_'), value]
        : [key, typeof value === 'object' && value !== null ? adjustKeys(value) : value]
    )
  )

然后在自定义的useTranslations钩子中做同样的转换：

export const useTranslations: typeof _useTranslations = (...args) => {
  const translateFn = _useTranslations(...args)

  return useMemo(() => {
    const proxyTranslateFn = new Proxy(translateFn, {
      apply(target, thisArg, argumentsList) {
        const [message, ...rest] = argumentsList
        return target.apply(thisArg, [message.replaceAll('.', '_'), ...rest])
      }
    }) as typeof translateFn

    // 复制原始函数的所有属性
    Reflect.ownKeys(translateFn).forEach(key => {
      const propertyDescriptor = Object.getOwnPropertyDescriptor(translateFn, key)
      if (propertyDescriptor) {
        Object.defineProperty(proxyTranslateFn, key, propertyDescriptor)
      }
    })

    return proxyTranslateFn
  }, [translateFn])
}

2. 官方推荐方案

Next-Intl官方推荐使用抽象标识符作为键名，并通过VSCode插件提供实时翻译预览功能。这种方式虽然需要额外配置，但能提供更好的开发体验和代码可维护性。

最佳实践建议

1. 对于小型项目或个人项目，可以使用键名转换方案快速实现需求
2. 对于大型团队项目，建议遵循官方推荐，使用抽象标识符
3. 无论采用哪种方案，都应保持一致性，避免混用两种模式
4. 考虑添加TypeScript类型定义，确保翻译键名的类型安全

通过理解这些解决方案，开发者可以根据项目需求选择最适合的国际化实现方式。