Localization
In Plenary, each translation of a piece of content is its own entry. An English and a Mexican Spanish version of a page are two entries of the same model, in the same site, with the same slug and different locale values. Reads ask for one locale and get exactly that translation, or a 404 if it does not exist.
How translations are stored
Section titled “How translations are stored”Every content entry has a locale, a lowercase language tag such as en, en-us, or es-mx. Translations of one page:
- belong to the same model and site,
- share a
slug(slugs are unique per site, model, and locale), - always share a folder and therefore a
path(see Content Directories), - are otherwise independent: each has its own
id, field values, status, schedule, and history.
[ { "id": "ff86df90-…", "slug": "spring-sale", "locale": "en-us", "status": "published", "path": "/blog" }, { "id": "df077cff-…", "slug": "spring-sale", "locale": "es-mx", "status": "draft", "path": "/blog" }]You can publish one translation while another is still a draft. On a singleton, there is one entry per site and locale.
A field’s Localized flag is a label for editors. It does not change storage: every field of an entry belongs to that entry’s locale.
Locale tags
Section titled “Locale tags”Locales are stored and compared in lowercase. ES-MX, es-MX, and es-mx are the same locale, and every response returns the lowercase form. A tag is a two- or three-letter language code followed by optional subtags separated by hyphens (^[a-z]{2,3}(-[a-z0-9]{2,8})*$). Underscores are not accepted: en_US is invalid.
Configure a site’s locales
Section titled “Configure a site’s locales”Each site has a list of locales and one default locale. Set them under Admin Settings → Site Management: pick the site, add tags under Locales with Add locale, and mark one with Make default.
- An entry can only be created or updated in one of its site’s locales (
422 entry_locale_not_allowed). - An entry created without a locale gets the site’s default locale.
- The default locale must be in the list (
422 site_default_locale_not_allowed). - Removing a locale from the list stops new content being written in it. Entries already stored in that locale stay readable.
A new site without explicit locales starts with the instance default, which self-hosted operators set as locale.default in plenary.yaml (en-us unless changed).
Create a translation
Section titled “Create a translation”In the console, create a new entry for the model, set its Locale to the target language, and give it the same URL Slug as the original. It joins the original’s folder automatically.
With the API, create an entry with the same slug and a different locale:
curl -X POST "https://your-instance.plenarycms.io/api/v1/content/article?site_key=default" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "spring-sale", "locale": "es-mx", "fields": { "title": "La venta de primavera empieza el lunes" } }'$PLENARY_API_KEY here must be a private key with content:entries:create; public keys cannot write content.
A translation cannot be created in a different folder from its siblings (422 entry_folder_translation_mismatch). Leave folder_id out and it inherits theirs.
How a read picks a locale
Section titled “How a read picks a locale”Reads that return one entry (by slug, or a singleton) match the locale exactly. List reads return only entries in that locale. The locale is chosen in this order:
- The
localequery parameter:?locale=es-mx. - The first tag of the
Accept-Languageheader. Only the first tag is used, soes-MX,es;q=0.9meanses-mx. A*or malformed header is ignored. - The site’s default locale, when the request names one site with
?site_key=, or uses an API key that belongs to a site. - The instance default locale (
locale.default).
A malformed ?locale= is an error (400 entry_locale_invalid); a malformed Accept-Language is ignored, because browsers set that header.
Fetching an entry by id ignores locale: the id already identifies one translation.
Always send locale explicitly. Server runtimes often send an Accept-Language of their own (Node’s fetch sends *), which makes the result depend on the environment rather than your code. The SDK always sends locale.
A where:locale= filter is combined with the resolved locale and can only narrow results. Use the locale parameter to choose a different one.
Fetch a translation with curl
Section titled “Fetch a translation with curl”curl "https://your-instance.plenarycms.io/api/v1/content/article/spring-sale?site_key=default&locale=es-mx" \ -H "X-API-KEY: $PLENARY_API_KEY"# Every published article in Mexican Spanishcurl "https://your-instance.plenarycms.io/api/v1/content/article?site_key=default&locale=es-mx" \ -H "X-API-KEY: $PLENARY_API_KEY"Fetch a translation with the SDK
Section titled “Fetch a translation with the SDK”createClient takes a default locale, sent on every request. Override it per call with the locale option.
import { createClient, PlenaryNotFoundError } from "@plenary/client";
export const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, apiKey: process.env.PLENARY_API_KEY!, siteKey: process.env.PLENARY_SITE_KEY!, locale: process.env.PLENARY_LOCALE ?? "en-us",});
// Return the article in the requested locale, or in the default locale if it// has not been translated yet.export async function getArticle(slug: string, locale: string) { try { return await plenary.getEntry("article", slug, { locale }); } catch (err) { if (err instanceof PlenaryNotFoundError && locale !== "en-us") { return plenary.getEntry("article", slug, { locale: "en-us" }); } throw err; }}The fallback in getArticle is your site’s choice, not Plenary’s. Leave it out if a missing translation should be a 404 on your site too.
To build a language switcher, list the translations that exist for a slug. Query each locale you support, since a list read covers one locale at a time:
import { plenary } from "./plenary";
const SUPPORTED_LOCALES = ["en-us", "es-mx"];
export async function availableLocales(slug: string): Promise<string[]> { const results = await Promise.all( SUPPORTED_LOCALES.map(async (locale) => { const { items } = await plenary.listEntries("article", { locale, where: { slug }, include: ["id"], limit: 1, }); return items.length > 0 ? locale : null; }), ); return results.filter((l): l is string => l !== null);}Related
Section titled “Related”- Sites: per-site locales and default locale.
- Entries & Publishing: create and publish each translation.
- Content API: the full read contract.
- @plenary/client:
createClient,getEntry,listEntries.