Localized fields or document variants?

A field-level model puts translations inside one document. An article might have a title object with English and Norwegian values. That is compact when the content structure is shared and editors usually work on the languages together. It becomes harder to manage if each language has a different publication schedule or substantially different page sections.

A document-level model creates an article document for each locale and links the variants through a translation group. Each variant can have its own draft, slug, review, and published version. That is the approach planned for Blockquote’s first localized content implementation.

Neither model decides which values should be shared. A product identifier may belong to a common base record, while its description is localized. An image might be shared in one campaign and locale-specific in another. Make that distinction explicit in the schema instead of letting editors guess.

Keep identity separate from localized URLs

Give the translation group a stable identity and every language variant its own document ID. Store slugs on the variants. An English page at /en/about can correspond to a Norwegian page at /nb/om-oss without pretending the slugs are the same identifier.

Define uniqueness within the relevant scope. A slug may need to be unique per site, document type, and locale. The frontend should resolve the language switcher through the translation group, not by replacing a substring in the current URL. Preserve redirects when editors change a published slug.

A translation can be a draft while the original is public

Independent variants allow an English article to remain published while a Norwegian version is under review. The delivery API should return only the published variant requested by the website. A draft in a translation group must not become publicly readable because another member of that group is published.

Shared values need versioning too. If a published translation reads a shared base record, decide whether it reads the latest base or the base revision captured at publication. Capturing a base revision makes the published result stable. Updating shared content then becomes an explicit publication decision.

Make fallback visible and predictable

If a requested translation is missing, a website can show a not-found page, offer another language, or use a configured fallback. The API should identify both the requested locale and the locale actually returned. That lets the frontend label the result and build the right links.

For a first implementation, whole-document fallback is easier to reason about than mixing translated and untranslated fields. A Norwegian heading with an English body may be acceptable for some applications, but it should be an intentional policy. Do not silently substitute a draft or publish an incomplete translation.

  • Document the default locale and the enabled locales.
  • Opt into fallback rather than applying it to every query.
  • Resolve references to a published variant in the requested locale.
  • Show missing translations in the editing interface.
  • Test enablement on an existing single-language site.

The current Blockquote status

Blockquote sites support opt-in localization with validated language tags, including regional and script variants. Linked document variants have independent drafts and publication. Delivery returns the requested language without silently falling back to another language.

Put it into practice

Choose a localization model that matches how people review and publish translations. Stable identities and explicit fallback matter as much as translated text.

Sources and further reading

These guides explain our design choices. For shipped functionality and current availability, see the product status.