Back to Details

generate-translations

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Translation Generation Guide

翻译生成指南

Payload has two separate translation systems:
  1. Core Translations - for core Payload packages (packages/ui, packages/payload, packages/next)
  2. Plugin Translations - for plugins (packages/plugin-*)
Payload 拥有两个独立的翻译系统：
  1. 核心翻译 - 用于核心 Payload 包（packages/ui、packages/payload、packages/next）
  2. 插件翻译 - 用于插件（packages/plugin-*）

Table of Contents

目录

1. Core Translations

1. 核心翻译

When to use: Adding translations to core Payload packages (packages/ui, packages/payload, packages/next)
使用场景： 向核心 Payload 包（packages/ui、packages/payload、packages/next）添加翻译时

Steps:

步骤：

  1. Add the English translation to 
    packages/translations/src/languages/en.ts
    • Add your new key/value to the appropriate section (e.g., 
      authentication
      , 
      general
      , 
      fields
      , etc.)
    • Use nested objects for organization
    • Example:
      typescript
      export const enTranslations = {
  authentication: {
    // ... existing keys
    newFeature: 'New Feature Text',
  },
}
  2. Add client key (if needed for client-side usage) to 
    packages/translations/src/clientKeys.ts
    • Add the translation key path using colon notation
    • Example: 
      'authentication:newFeature'
    • Client keys are used for translations that need to be available in the browser
  3. Generate translations for all languages
    • Change directory: 
      cd tools/scripts
    • Run: 
      pnpm generateTranslations:core
    • This auto-translates your new English keys to all other supported languages
  1. 将英文翻译添加到 
    packages/translations/src/languages/en.ts
    • 将新的键/值对添加到对应章节（例如 
      authentication
      、
      general
      、
      fields
      等）
    • 使用嵌套对象进行组织
    • 示例：
      typescript
      export const enTranslations = {
  authentication: {
    // ... 现有键
    newFeature: 'New Feature Text',
  },
}
  2. 添加客户端键（如果需要在客户端使用）到 
    packages/translations/src/clientKeys.ts
    • 使用冒号表示法添加翻译键路径
    • 示例：
      'authentication:newFeature'
    • 客户端键用于需要在浏览器/管理UI中可用的翻译
  3. 为所有语言生成翻译
    • 切换目录：
      cd tools/scripts
    • 运行命令：
      pnpm generateTranslations:core
    • 此命令会自动将新的英文键翻译为所有其他支持的语言

2. Plugin Translations

2. 插件翻译

When to use: Adding translations to any plugin package (packages/plugin-*)
使用场景： 向任何插件包（packages/plugin-*）添加翻译时

Steps:

步骤：

  1. Verify plugin has translations folder
    • Check if 
      packages/plugin-{name}/src/translations
      exists
    • If it doesn't exist, see "Scaffolding New Plugin Translations" below
  2. Add the English translation to the plugin's 
    packages/plugin-{name}/src/translations/languages/en.ts
    • Plugin translations are namespaced under the plugin name
    • Example for plugin-multi-tenant:
      typescript
      export const enTranslations = {
  'plugin-multi-tenant': {
    'new-feature-label': 'New Feature',
  },
}
  3. Generate translations for all languages
    • Change directory: 
      cd tools/scripts
    • Run the plugin-specific script: 
      pnpm generateTranslations:plugin-{name}
    • Examples: 
      • pnpm generateTranslations:plugin-multi-tenant
      • pnpm generateTranslations:plugin-ecommerce
      • pnpm generateTranslations:plugin-import-export
  1. 验证插件是否有翻译文件夹
    • 检查 
      packages/plugin-{name}/src/translations
      是否存在
    • 如果不存在，请查看下方的「搭建新插件翻译框架」
  2. 将英文翻译添加到插件的 
    packages/plugin-{name}/src/translations/languages/en.ts
    • 插件翻译会自动以插件名称作为命名空间
    • 以 plugin-multi-tenant 为例：
      typescript
      export const enTranslations = {
  'plugin-multi-tenant': {
    'new-feature-label': 'New Feature',
  },
}
  3. 为所有语言生成翻译
    • 切换目录：
      cd tools/scripts
    • 运行插件专属脚本：
      pnpm generateTranslations:plugin-{name}
    • 示例： 
      • pnpm generateTranslations:plugin-multi-tenant
      • pnpm generateTranslations:plugin-ecommerce
      • pnpm generateTranslations:plugin-import-export

Scaffolding New Plugin Translations

搭建新插件翻译框架

If a plugin doesn't have a translations folder yet, ask the user if they want to scaffold one.
如果插件还没有翻译文件夹，请询问用户是否需要搭建一个。

Structure to create:

要创建的结构：

packages/plugin-{name}/src/translations/
├── index.ts
├── types.ts
└── languages/
    ├── en.ts
    ├── es.ts
    └── ... (all other language files)
packages/plugin-{name}/src/translations/
├── index.ts
├── types.ts
└── languages/
    ├── en.ts
    ├── es.ts
    └── ... (所有其他语言文件)

Files to create:

要创建的文件：

  1. types.ts - Define the plugin's translation types
  2. index.ts - Export all translations and re-export types
  3. languages/en.ts - English translations (the source for generation)
  4. languages/*.ts - Other language files (initially empty, will be generated)
  1. types.ts - 定义插件的翻译类型
  2. index.ts - 导出所有翻译并重新导出类型
  3. languages/en.ts - 英文翻译（生成的源文件）
  4. languages/*.ts - 其他语言文件（初始为空，将通过生成脚本填充）

Generation script to create:

要创建的生成脚本：

  1. Create 
    tools/scripts/src/generateTranslations/plugin-{name}.ts
    • Use 
      plugin-multi-tenant.ts
      as a template
    • Update the import paths to point to the new plugin
    • Update the targetFolder path
  2. Add script to 
    tools/scripts/package.json
    :
    json
    "generateTranslations:plugin-{name}": "node --no-deprecation --import @swc-node/register/esm-register src/generateTranslations/plugin-{name}.ts"
  1. 创建 
    tools/scripts/src/generateTranslations/plugin-{name}.ts
    • 以 
      plugin-multi-tenant.ts
      为模板
    • 更新导入路径以指向新插件
    • 更新 targetFolder 路径
  2. 向 
    tools/scripts/package.json
    添加脚本：
    json
    "generateTranslations:plugin-{name}": "node --no-deprecation --import @swc-node/register/esm-register src/generateTranslations/plugin-{name}.ts"

Important Notes

重要说明

  • All translation generation requires 
    OPENAI_KEY
    environment variable to be set
  • The generation scripts use OpenAI to translate from English to other languages
  • Always add translations to English first - it's the source of truth
  • Core translations: Client keys are only needed for translations used in the browser/admin UI
  • Plugin translations: Automatically namespaced under the plugin name to avoid conflicts
  • 所有翻译生成都需要设置 
    OPENAI_KEY
    环境变量
  • 生成脚本使用 OpenAI 将英文翻译为其他语言
  • 始终先添加英文翻译 - 它是唯一的可信源
  • 核心翻译：仅在浏览器/管理UI中使用的翻译才需要客户端键
  • 插件翻译：会自动以插件名称作为命名空间，避免冲突