generate-translations

用途

generate-translations 用于在向 Payload 的包中添加新的翻译键后，生成对应的多语言翻译字符串。Payload 包含两套独立的翻译系统：核心翻译（Core Translations）和插件翻译（Plugin Translations），该技能分别针对这两套系统提供操作指引。

主要能力

核心翻译

适用于向核心 Payload 包（packages/ui、packages/payload、packages/next）添加翻译。步骤包括：

在 packages/translations/src/languages/en.ts 中添加英文翻译，将新的键/值添加到合适的区块（如 authentication、general、fields 等），使用嵌套对象进行组织。示例：

export const enTranslations = { authentication: { // ... existing keys newFeature: 'New Feature Text', }, }

如客户端侧需要使用，在 packages/translations/src/clientKeys.ts 中添加客户端键，使用冒号表示法添加翻译键路径，例如 'authentication:newFeature'。客户端键用于需要在浏览器中可用的翻译。
为所有语言生成翻译：切换到 tools/scripts 目录，运行 pnpm generateTranslations:core。该命令会将新的英文键自动翻译为所有其他支持的语言。

插件翻译

适用于向任意插件包（packages/plugin-*）添加翻译。步骤包括：

确认插件是否已有 translations 文件夹，检查 packages/plugin-{name}/src/translations 是否存在。若不存在，参见下方的“为新插件搭建翻译结构”。
在插件的 packages/plugin-{name}/src/translations/languages/en.ts 中添加英文翻译。插件翻译以插件名作为命名空间。以 plugin-multi-tenant 为例：

export const enTranslations = { 'plugin-multi-tenant': { 'new-feature-label': 'New Feature', }, }

为所有语言生成翻译：切换到 tools/scripts 目录，运行插件专属脚本 pnpm generateTranslations:plugin-{name}。示例：

pnpm generateTranslations:plugin-multi-tenant pnpm generateTranslations:plugin-ecommerce pnpm generateTranslations:plugin-import-export

为新插件搭建翻译结构

如果插件尚无 translations 文件夹，可询问用户是否需要搭建。需要创建的结构如下：

packages/plugin-{name}/src/translations/ ├── index.ts ├── types.ts └── languages/ ├── en.ts ├── es.ts └── ... (all other language files)

需要创建的文件：

types.ts - 定义插件的翻译类型 index.ts - 导出所有翻译并重新导出类型 languages/en.ts - 英文翻译（生成的源文件） languages/*.ts - 其他语言文件（初始为空，将被生成）

需要创建的生成脚本：

创建 tools/scripts/src/generateTranslations/plugin-{name}.ts，以 plugin-multi-tenant.ts 为模板，更新导入路径指向新插件，更新 targetFolder 路径。

在 tools/scripts/package.json 中添加脚本：

"generateTranslations:plugin-{name}": "node --no-deprecation --import @swc-node/register/esm-register src/generateTranslations/plugin-{name}.ts"

使用方式

核心翻译通过 pnpm generateTranslations:core 生成，插件翻译通过 pnpm generateTranslations:plugin-{name} 生成。所有翻译生成均需设置 OPENAI_KEY 环境变量，生成脚本使用 OpenAI 将英文翻译为其他语言。

适用场景

适用于 Payload 核心包或插件包中新增翻译键后，需要批量生成多语言翻译字符串的开发场景。

限制与注意事项

所有翻译生成都需要设置 OPENAI_KEY 环境变量。
生成脚本使用 OpenAI 从英文翻译为其他语言。
始终先添加英文翻译，英文是唯一事实来源。
核心翻译：仅浏览器/管理界面使用的翻译才需要客户端键。
插件翻译：自动以插件名作为命名空间以避免冲突。