Add a language

Everything that knows about languages reads src/i18n/locales.ts: Payload's localization, routing, the language switcher, hreflang, the sitemap and the translation tools. Adding a language starts with one entry there. Swedish as an example:

1. The entry #

export const locales = [
  { code: 'en', label: 'English', hreflang: 'en', ogLocale: 'en_US', isDefault: true },
  { code: 'da', label: 'Dansk', hreflang: 'da', ogLocale: 'da_DK', region: 'DK' },
  { code: 'de', label: 'Deutsch', hreflang: 'de', ogLocale: 'de_DE', region: 'DE' },
  { code: 'sv', label: 'Svenska', hreflang: 'sv', ogLocale: 'sv_SE', region: 'SE' },
] as const satisfies readonly LocaleDef[]

Languages explains each field. Restart the development server. The site now answers at /sv/…, the admin's language picker offers Svenska, and every text falls back to English until it is translated.

On PostgreSQL the languages are part of the database schema: create and run a migration (pnpm payload migrate:create, then pnpm payload migrate). MongoDB needs nothing.

2. Interface texts #

Copy src/messages/en.json to src/messages/sv.json and translate the values; keep the keys. Without the file, Swedish visitors read the default language's interface texts, and editors can still override any of them in Microcopy.

The key check in src/utilities/microcopy.test.ts imports the language files by name: add the new file there, so a missing key fails the test.

3. Words in addresses #

Collection addresses have a word per language in the registry (src/registry/index.ts): segments such as { en: 'news', da: 'nyheder' }, facet words such as topic, and the labels cards show. Add the new language's word to each; without it, its addresses use the default language's word (/sv/news).

Slugs are made from titles by src/utilities/slugify.ts, which spells out Nordic and other Latin letters with accents (ø becomes oe) and drops anything else. For a language in another script, add its letters to TRANSLIT, or editors type the slugs themselves.

4. Translation #

The AI translation needs nothing for a new language: it names languages with the browser's own language names. One optional tuning: if the language writes compounds as one word, as German and the Nordic languages do, add it to LANGUAGE_TRAITS in src/utilities/translate/languages.ts, so the glossary check finds a term inside a longer word.

Then, in the admin, editors can:

• give the language its own notes and examples in the Translation style guide, and its decisions in the Glossary;
• translate the site with ✨ Translate or "Translate the whole site" in Translation status;
• import existing translations under Import translations.

5. The demo and the tests #

The demo seed writes English and Danish only, and a few tests name da and de paths. A new language needs nothing there, but it is not covered by them either.