I18n

Admin Panel 已翻译成 30 多种语言，并且还在不断增加。借助 I18n，编辑者可以使用他们偏好的语言浏览界面并读取 API 错误消息。这类似于本地化 (Localization)，但不同的是，I18n 管理的是应用程序界面的翻译，而不是数据本身的翻译。

默认情况下，Payload 预装了英文，但您可以轻松地将其他语言加载到自己的应用程序中。语言会根据请求自动检测。如果未检测到语言，或者用户的语言尚未被您的应用程序支持，将默认使用英文。

要在项目中添加 I18n，您首先需要安装 @payloadcms/translations 包：

pnpm install @payloadcms/translations

安装完成后，可以在 Payload Config 中使用 i18n 键进行配置：

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  i18n: {
    
    // ...
  },
})

配置选项

您可以轻松自定义并覆盖 Payload 默认提供的任何 i18n 设置。Payload 将使用您的自定义选项，并将其与自己的选项合并。

import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  i18n: {
    fallbackLanguage: 'en', // default
  },
})

以下选项可用：

选项	描述
fallbackLanguage	如果用户的首选语言不受支持，将回退到的语言。默认为 'en'。
translations	一个包含翻译的对象。键是语言代码，值是对应的翻译。
supportedLanguages	一个包含支持的语言的对象。键是语言代码，值是对应的翻译。

添加语言

您可以通过为新语言提供翻译，轻松地将新语言添加到您的 Payload 应用程序中。Payload 提供了一些内置的翻译，可以从 @payloadcms/translations 导入，但您也可以提供自己的自定义翻译来支持任何语言。

要添加新语言，请在您的 Payload 配置中使用 i18n.supportedLanguages 键：

import { buildConfig } from 'payload'
import { en } from '@payloadcms/translations/languages/en'
import { de } from '@payloadcms/translations/languages/de'

export default buildConfig({
  // ...
  i18n: {
    supportedLanguages: { en, de },
  },
})

TIP

最好只支持您需要的语言，以便将捆绑的 JavaScript 最小化，从而减少项目的负担。

自定义翻译

您可以通过扩展现有语言或完全添加新语言来定制 Payload 的内置翻译。这可以通过将新的翻译字符串注入现有语言，或者提供全新的语言键来完成。

要添加自定义翻译，请在您的 Payload 配置中使用 i18n.translations 键：

import { buildConfig } from 'payload'

export default buildConfig({
  //...
  i18n: {
    translations: {
      en: {
        custom: {
          // namespace can be anything you want
          key1: 'Translation with {{variable}}', // translation
        },
        // override existing translation keys
        general: {
          dashboard: 'Home',
        },
      },
    },
  },
  //...
})

项目翻译

虽然 Payload 的内置功能已经完全翻译，您可能还希望翻译您自己项目的部分内容。这可以在如 Collections 和 Globals 等地方实现，例如它们的标签和组、字段标签、描述或输入占位符文本。

要实现此功能，在适用的地方提供翻译，并使用语言代码作为键：

import type { CollectionConfig } from 'payload'

export const Articles: CollectionConfig = {
  slug: 'articles',
  labels: {
    singular: {
      en: 'Article',
      es: 'Artículo',
    },
    plural: {
      en: 'Articles',
      es: 'Artículos',
    },
  },
  admin: {
    group: {
      en: 'Content',
      es: 'Contenido',
    },
  },
  fields: [
    {
      name: 'title',
      type: 'text',
      label: {
        en: 'Title',
        es: 'Título',
      },
      admin: {
        placeholder: {
          en: 'Enter title',
          es: 'Introduce el título',
        },
      },
    },
  ],
}

更改语言

用户可以在其账户设置中更改首选语言，或者通过其他方式修改用户偏好设置。

Node.js

Payload 的后台会在处理传入请求之前设置语言。这使得后台验证能够返回用户自己语言的错误消息，或者系统生成的电子邮件可以使用正确的翻译发送。您可以通过带有 accept-language 头的 HTTP 请求，Payload 将使用该语言。

在 Payload 应用程序中的任何地方，只要您可以访问 req 对象，就可以访问分配给 req.i18n 的 Payload 强大的国际化功能。要访问文本翻译，您可以使用 req.t('namespace:key')。

TypeScript

为了在您的项目中使用自定义翻译，您需要为翻译提供类型。

在这里，我们创建一个可共享的翻译对象。我们将在自定义组件和 Payload 配置中都导入它。

在这个示例中，我们展示了如何扩展英语，但您也可以对任何您想要的语言做同样的操作。

// <rootDir>/custom-translations.ts

import { enTranslations } from '@payloadcms/translations/languages/en'
import type { NestedKeysStripped } from '@payloadcms/translations'

export const customTranslations = {
  en: {
    general: {
      myCustomKey: 'My custom english translation',
    },
    fields: {
      addLabel: 'Add!',
    },
  },
}

export type CustomTranslationsObject = typeof customTranslations.en &
  typeof enTranslations
export type CustomTranslationsKeys =
  NestedKeysStripped<CustomTranslationsObject>

将共享的翻译对象导入到我们的 Payload 配置中，以便它们可以被使用：

// <rootDir>/payload.config.ts

import { buildConfig } from 'payload'

import { customTranslations } from './custom-translations'

export default buildConfig({
  //...
  i18n: {
    translations: customTranslations,
  },
  //...
})

将共享的翻译类型导入到您的自定义组件中以便使用：

// <rootDir>/components/MyComponent.tsx

'use client'
import type React from 'react'
import { useTranslation } from '@payloadcms/ui'

import type {
  CustomTranslationsObject,
  CustomTranslationsKeys,
} from '../custom-translations'

export const MyComponent: React.FC = () => {
  const { i18n, t } = useTranslation<
    CustomTranslationsObject,
    CustomTranslationsKeys
  >() // These generics merge your custom translations with the default client translations

  return t('general:myCustomKey')
}

此外，Payload 在多个地方暴露了 t 函数，例如在标签中。以下是如何为这些函数进行类型定义：

// <rootDir>/fields/myField.ts

import type {
  DefaultTranslationKeys,
  TFunction,
} from '@payloadcms/translations'
import type { Field } from 'payload'

import { CustomTranslationsKeys } from '../custom-translations'

const field: Field = {
  name: 'myField',
  type: 'text',
  label: ({ t: defaultT }) => {
    const t = defaultT as TFunction<CustomTranslationsKeys>
    return t('fields:addLabel')
  },
}