i18n

The i18n plugin scopes content by language. Each root belongs to one language, sibling-language versions of an entry are tied together by a translation group, and reads fall back along a chain you configure.

Installation

Add it to your config

Pass the static set of languages (as a const tuple, so they become a typed union) and a defaultLanguage:

import { createCMS } from '@createcms/core';
import { i18n } from '@createcms/core/plugins/i18n';

export const cms = createCMS({
  db,
  collections,
  media,
  authMiddleware,
  plugins: [
    i18n({
      languages: ['en', 'de', 'fr'],
      defaultLanguage: 'en',
      fallback: { de: ['en'], fr: ['en'] },
    }),
  ],
});

Update the database

The plugin adds language columns. Regenerate the schema file, then apply it to your database with your Drizzle migration workflow:

npx createcms generate
npx drizzle-kit generate && npx drizzle-kit migrate

The drizzle-kit commands need a drizzle.config.ts at your project root — see the Quickstart for the one to create.

Usage

The active language is resolved per request from your middleware and applied to every query. These two methods are contributed to every collection, so they live at cms.api.<collection>.<method> (and on the client as client.<collection>.<method> with identical types). They only exist when the i18n plugin is installed.

Create a Translation

Create a sibling-language version of an existing entry, so a page can live in every language you support. The new entry joins the source's translation group (translationKey), takes the target language, and (by default) seeds its draft from a copy of the source's main tree. The source must exist in the active language.

const data = await cms.api.pages.createTranslation({
  body: {
    sourceRootId: 'root_abc', // required
    targetLanguage: 'de', // required
    seed: 'copy',
  },
});

const { data, error } = await client.pages.createTranslation({
  body: {
    sourceRootId: 'root_abc', // required
    targetLanguage: 'de', // required
    seed: 'copy',
  },
});

List an Entry's Translations

List every language variant (sibling) of an entry, tied together by their translation group. Diff the returned languages against your configured languages to see which ones you still need to translate. It works cross-language by design: you pass a rootId from the active language, and the siblings you get back span the whole group.

const data = await cms.api.pages.listTranslations({
  query: { rootId: 'root_abc' }, // required
});

const { data, error } = await client.pages.listTranslations({
  query: { rootId: 'root_abc' }, // required
});

Variables and templates

Variables and templates scope by language too, with the same fallback chain: a value defined only in the default language is inherited by every language that falls back to it, and only the languages that need a different value override it.

// companyName: only defined in the default language 'en' = 'Acme'
// cta:         'en' = 'Buy now', 'de' = 'Jetzt kaufen'
// reading a German page:
//   {{companyName}} → 'Acme'          (fell back to en)
//   {{cta}}         → 'Jetzt kaufen'  (de override)

Managing variables and templates always targets the exact active language, not a fallback cell — so in German you manage German values. Uniqueness for both is scoped per language, so a variable's key (or a template's (collection, blockType, propertyKey)) is free to differ per language.

Missing translations, routing and SEO

The plugin resolves PAGES strictly per language on purpose: a root without a sibling in the active language does not exist in that scope, and reads return a 404 instead of silently serving another language. The fallback chain applies one level below, inside a page: references resolve to the best sibling along [language, ...fallback], internal links point at the active-language sibling when one exists, and variables inherit along the chain. An explicit empty chain (fallback: { en: [] }) opts a language out of fragment fallback too.

For your routing this means the 404 is a decision the app makes, and two patterns are sound:

• Do not link what does not exist: build the language switcher and the sitemap from listTranslations, emit hreflang pairs only for existing siblings plus an x-default pointing at the default language, and let a direct request for a missing translation return 404.
• Or redirect: answer a missing translation with a temporary redirect (302 or 307) to the default-language URL, so the content has exactly one URL per language it exists in.

Avoid serving default-language content under another language's URL: the same content becomes indexable under several URLs, the page language contradicts the URL and any hreflang annotation, and when the translation later arrives its URL has to displace the indexed fallback.

Schema

Options

Error codes

There is intentionally no I18N_NOT_ENABLED code: createTranslation / listTranslations only exist when the plugin is installed, so "i18n not enabled" is the structural absence of the endpoint, not a runtime error.