Payload CMS 自定义翻译类型的最佳实践

在 Payload CMS 项目中，处理自定义翻译类型是一个常见需求。开发者经常需要为特定函数如 useTranslation 或 getNextRequestI18n 传递自定义翻译泛型参数，以确保获得正确的翻译类型。然而，目前 getLocalI18n、req.i18n 和 req.t 等 Payload 钩子函数中缺乏对这些自定义翻译类型的支持。

问题背景

在 Payload CMS 的国际化(i18n)实现中，类型安全是一个重要考量。开发者希望能够为自定义翻译键名定义类型，以便在代码中获得更好的类型提示和编译时检查。虽然一些核心函数已经支持通过泛型参数传递自定义翻译类型，但部分钩子函数尚未提供相同的支持。

当前解决方案

对于 req.t 这类函数，Payload 团队推荐使用类型断言(Type Assertion)的方式来实现类型安全。具体做法是使用 TFunction 类型进行类型转换：

import type { TFunction } from '@payloadcms/translations'

const t = req.t as TFunction<YourCustomKeys>

这种方法虽然有效，但并不是最理想的解决方案，因为它依赖于类型断言而非真正的类型参数支持。

技术考量

Payload 团队在考虑是否要为 getLocalI18n 等函数添加泛型支持时，做出了谨慎的决定。主要基于以下技术考量：

1. 类型参数滥用问题：使用类型参数作为类型转换工具并不是 TypeScript 的最佳实践，这会导致代码意图不清晰。

2. 内部实现一致性：即使添加了泛型参数，内部实现仍然需要进行类型转换，与直接使用类型断言效果相同。

3. 向后兼容性：保持现有 API 的稳定性，避免引入破坏性变更。

最佳实践建议

基于 Payload CMS 的当前实现，建议开发者采用以下方式处理自定义翻译类型：

1. 核心函数：对于支持泛型的函数，直接使用泛型参数传递自定义翻译类型。

2. 钩子函数：对于不支持泛型的钩子函数，使用类型断言的方式确保类型安全。

3. 类型定义：明确定义自定义翻译键名的类型，保持项目中翻译键名的一致性。

// 定义自定义翻译键名类型
type MyCustomTranslations = {
  welcome: string
  goodbye: string
  // 其他翻译键...
}

// 在支持泛型的函数中使用
const { t } = useTranslation<MyCustomTranslations>()

// 在不支持泛型的钩子中使用类型断言
const t = req.t as TFunction<MyCustomTranslations>

未来展望

虽然当前解决方案能够满足需求，但 Payload 团队仍在持续改进国际化支持。开发者可以期待未来版本中更完善的类型支持和更优雅的 API 设计。同时，团队也在努力完善相关文档，帮助开发者更好地理解和使用这些功能。

通过遵循这些最佳实践，开发者可以在 Payload CMS 项目中实现类型安全的国际化解决方案，同时保持代码的清晰和可维护性。