Translations

Localization stores chosen fields once per language, while every other field stays shared. An article's title and body get a Polish version, but whether it is featured stays one value. Translated values live in a second table, {tableName}_translations, with one row per record and language. This guide uses example.localized-article from the example plugin.

Before you beginCopy Anchor Link

The languages come from your app's i18n.locales in vitnode.config.ts (see Languages & Localization) and from the languages created at install. defaultLocale must be one of them. A language turned off in the config stays readable in the AdminCP, but nobody can write to it and the public API does not serve it.

export const localizedArticleContentType = defineContentType({
  id: "example.localized-article",
  tableName: "example_localized_articles",
  localization: {
    defaultLocale: "en",
    fallback: "default",
  },
  publication: true,
  fields: {
    title: field.text({
      localized: true,
      required: true,
      minLength: 3,
      maxLength: 200,
    }),
    slug: field.slug({ localized: true, source: "title" }),
    body: field.textarea({ localized: true, required: true }),
    featured: field.boolean({ defaultValue: false }),
  },
});

export const localizedArticleContent = createContentModel(
  localizedArticleContentType,
);

export const example_localized_articles = localizedArticleContent.table;
export const example_localized_articles_translations =
  localizedArticleContent.translationTable;

bun run build:plugins && bun run db:migrate

Edit languages in the AdminCPCopy Anchor Link

There are no language tabs. Each localized field carries its own language selector, so an editor can fix the Polish title without leaving the form. The field first shows your AdminCP language if it has text, then the default language, then any language that has text. Shared fields have no selector.

This is the blog plugin's category dialog, where name is field.text({ localized: true }):

Saving the form sends the shared fields and every language you typed into in one request: POST /localized for a new record, PUT /{id}/localized for an existing one. The server writes them in one transaction. A new record must include its default language. A Polish-only edit does not touch the shared row, so it does not bump the record's version or expire the English cache.

With publication, each language has its own status. Publishing the record publishes its languages too, and you can then unpublish one language alone. A translation is public only when both the record and that translation are published. With editorial, each language also keeps its own revisions and preview links.

Read a language from the public APICopy Anchor Link

The public API serves one language per request, chosen in this order:

1. The ?locale= query parameter. A locale that the site does not serve returns 404.
2. Otherwise the Accept-Language header. The response then carries Vary: Accept-Language.
3. Otherwise defaultLocale.

curl -i "http://localhost:3000/api/@vitnode/example/content/localized-articles/witaj-content-engine?locale=pl"

HTTP/1.1 200
content-language: pl

{"title":"Witaj Content Engine","slug":"witaj-content-engine","body":"Jeden rekord, dwa języki.","featured":false,"publishedAt":"2026-10-10T10:57:12.452Z","locale":"pl"}

The locale property says which language the body is in. When the requested translation is missing or unpublished, fallback: "default" serves the default language instead, so "locale" becomes "en". With fallback: "none" (the default), the API returns 404.

In a page loader, pass the route's locale through. This is the example plugin's localized article page:

const detail = await fetcher({
  plugin: CONFIG_PLUGIN.pluginId,
  method: "get",
  module: "content/localized-articles",
  path: "/{slug}",
  args: {
    params: { slug: encodeURIComponent(slug) },
    query: { locale },
  },
});

Opening /pl/localized-articles/witaj-content-engine renders the Polish translation:

Each translation can have its own slug and URL; Public pages covers localized URLs and hreflang.

Translation routesCopy Anchor Link

buildContentAdminModule adds staff routes for each language under the content type's admin path. They use the same staff permissions as the record:

Each translation write emits an event such as content.example.localized-article.translation_created or translation_published; see Events.

OptionsCopy Anchor Link