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.

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.