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 with 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 was 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    debug: false, // default
8  }
9})

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'`.
`debug`	Whether to log debug information to the console. Default is `false`.
`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 { 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 is an example of how you can define the types for the custom translations in a Custom Component:

1'use client'
2import type { NestedKeysStripped } from '@payloadcms/translations'
3import type React from 'react'
4
5import { useTranslation } from '@payloadcms/ui/providers/Translation'
6
7const customTranslations = {
8  en: {
9    general: {
10      test: 'Custom Translation',
11    },
12  },
13}
14
15type CustomTranslationObject = typeof customTranslations.en
16type CustomTranslationKeys = NestedKeysStripped<CustomTranslationObject>
17
18export const MyComponent: React.FC = () => {
19  const { i18n, t } = useTranslation<CustomTranslationObject, CustomTranslationKeys>() // These generics merge your custom translations with the default client translations
20
21  return t('general:test')
22}

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

1import type {
2  DefaultTranslationKeys,
3  NestedKeysStripped,
4  TFunction,
5} from '@payloadcms/translations'
6import type { Field } from 'payload'
7
8const customTranslations = {
9  en: {
10    general: {
11      test: 'Custom Translation',
12    },
13  },
14}
15
16type CustomTranslationObject = typeof customTranslations.en
17type CustomTranslationKeys = NestedKeysStripped<CustomTranslationObject>
18
19const field: Field = {
20  name: 'myField',
21  type: 'text',
22  label: (
23    { t }: { t: TFunction<CustomTranslationKeys | DefaultTranslationKeys> }, // The generic passed to TFunction does not automatically merge the custom translations with the default translations. We need to merge them ourselves here
24  ) => t('fields:addLabel'),
25}

Deploy your entire stack in one place with Payload Cloud.

Microsoft chose Payload to tell the world about AI.

I18n