I18n

The Admin Panel is translated in over 30 languages and counting. With I18n, editors can navigate the interface and read API error messages in their preferred language. This is similar to Localization, but instead of managing translations for the data itself, you are managing translations for your application's interface.

By default, Payload comes preinstalled with English, but you can easily load other languages into your own application. Languages are automatically detected based on the request. If no language is detected, or if the user's language is not yet supported by your application, English will be chosen.

To configure I18n, use the i18n key in your Payload Config:

1import { buildConfig } from 'payload'
2
3export default buildConfig({
4  // ...
5  i18n: { 
6    // ...
7  },
8})

Config Options

You can easily customize and override any of the i18n settings that Payload provides by default. Payload will use your custom options and merge them in with its own.

1import { buildConfig } from 'payload'
2
3export default buildConfig({
4  // ...
5  i18n: {
6    fallbackLanguage: 'en', // default
7  }
8})

The following options are available:

Option	Description
`fallbackLanguage`	The language to fall back to if the user's preferred language is not supported. Default is `'en'`.
`translations`	An object containing the translations. The keys are the language codes and the values are the translations.
`supportedLanguages`	An object containing the supported languages. The keys are the language codes and the values are the translations.

Adding Languages

You can easily add new languages to your Payload app by providing the translations for the new language. Payload maintains a number of built-in translations that can be imported from @payloadcms/translations, but you can also provide your own Custom Translations to support any language.

To add a new language, use the i18n.supportedLanguages key in your Payload Config:

1import { buildConfig } from 'payload'
2import { en } from '@payloadcms/translations/languages/en'
3import { de } from '@payloadcms/translations/languages/de'
4
5export default buildConfig({
6  // ...
7  i18n: {
8    supportedLanguages: { en, de },
9  },
10})

Custom Translations

You can customize Payload's built-in translations either by extending existing languages or by adding new languages entirely. This can be done by injecting new translation strings into existing languages, or by providing an entirely new language keys altogether.

To add Custom Translations, use the i18n.translations key in your Payload Config:

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

Project Translations

While Payload's built-in features come fully translated, you may also want to translate parts of your own project. This is possible in places like Collections and Globals, such as on their labels and groups, field labels, descriptions or input placeholder text.

To do this, provide the translations wherever applicable, keyed to the language code:

1import type { CollectionConfig } from 'payload'
2
3export 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'
      },
    },
  },
],
37}

Node

Payload's backend sets the language on incoming requests before they are handled. This allows backend validation to return error messages in the user's own language or system generated emails to be sent using the correct translation. You can make HTTP requests with the accept-language header and Payload will use that language.

Anywhere in your Payload app that you have access to the req object, you can access Payload's extensive internationalization features assigned to req.i18n. To access text translations you can use req.t('namespace:key').

TypeScript

In order to use custom translations in your project, you need to provide the types for the translations.

Here we create a shareable translations object. We will import this in both our custom components and in our Payload config.

1// <rootDir>/custom-translations.ts
2
3import type { Config } from 'payload'
4import type { NestedKeysStripped } from '@payloadcms/translations'
5
6export const customTranslations: Config['i18n']['translations'] = {
7  en: {
8    general: {
9      myCustomKey: 'My custom english translation',
10    },
11    fields: {
12      addLabel: 'Add!',
13    }
14  },
15}
16
17export type CustomTranslationsObject = typeof customTranslations.en
18export type CustomTranslationsKeys = NestedKeysStripped<CustomTranslationsObject>

Import the shared translations object into our Payload config so they are available for use:

1// <rootDir>/payload.config.ts
2
3import { buildConfig } from 'payload'
4
5import { customTranslations } from './custom-translations'
6
7export default buildConfig({
8  //...
9  i18n: {
10    translations: customTranslations,
11  },
12  //...
13})

Import the shared translation types to use in your Custom Component:

1// <rootDir>/components/MyComponent.tsx
2
3'use client'
4import type React from 'react'
5import { useTranslation } from '@payloadcms/ui'
6
7import type { CustomTranslationsObject, CustomTranslationsKeys } from '../custom-translations'
8
9export const MyComponent: React.FC = () => {
10  const { i18n, t } = useTranslation<CustomTranslationsObject, CustomTranslationsKeys>() // These generics merge your custom translations with the default client translations
11
12  return t('general:myCustomKey')
13}

Additionally, Payload exposes the t function in various places, for example in labels. Here is how you would type those:

1// <rootDir>/fields/myField.ts
2
3import type { DefaultTranslationKeys, TFunction } from '@payloadcms/translations'
4import type { Field } from 'payload'
5
6import { CustomTranslationsKeys } from '../custom-translations'
7
8const field: Field = {
9  name: 'myField',
10  type: 'text',
11  label: (
12    { t }: { t: TFunction<CustomTranslationsKeys | DefaultTranslationKeys> }, // The generic passed to TFunction does not automatically merge the custom translations with the default translations. We need to merge them ourselves here
13  ) => t('fields:addLabel'),
14}

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.