Localized content resolution
Resolve versioned published or preview content through locale fallbacks and an adapter-owned CMS source.
@puzzle-ui/i18n/content provides a framework- and CMS-independent content
resolver. Implement ContentSource around the CMS or database already used by
your application:
import { createContentResolver } from "@puzzle-ui/i18n/content";
const content = createContentResolver({
registry: i18n.registry,
source: {
async load({ locale, slug, version, preview }, signal) {
return cms.getLocalizedDocument({
locale,
slug,
version,
includeDrafts: preview,
signal,
});
},
},
validate(content) {
articleSchema.parse(content);
},
});Resolve a page with a locale and localized slug:
const result = await content.resolve({
locale: "nl",
slug: "artikelen/hello",
version: 3,
});The resolver checks the registry fallback chain in order and returns a
discriminated found or missing result. A found result reports the requested
and resolved locales and whether fallback was used. Draft documents are
excluded unless preview: true; requested versions that are unavailable
resolve as missing. Source errors, aborts, mismatched locales/slugs, and schema
validation failures are surfaced rather than silently replaced.
The resolver rejects absolute, traversal, query, fragment, malformed-encoding,
and encoded-separator slugs. The source must honor the requested version and
preview mode where possible. Authenticate and authorize preview requests in
your server boundary before setting preview: true; the flag is not an access
control mechanism. The included API is an adapter contract, not a Sanity,
Contentful, or other vendor-specific integration.
The resolver freezes the returned document envelope, not arbitrary nested
content. Validate CMS data against an application schema and escape or render
rich text with a safe renderer; never inject untrusted content with
dangerouslySetInnerHTML.
Sanity source
For Sanity, createSanityContentSource adapts an injected client without
adding a Sanity SDK dependency:
import {
createContentResolver,
createSanityContentSource,
} from "@puzzle-ui/i18n/content";
const source = createSanityContentSource<Article>(
{
fetch: (query, params, options) =>
sanityClient.fetch(query, params, options),
},
{ documentType: "article", cacheTtlMs: 30_000 },
);
const articles = createContentResolver({
registry: i18n.registry,
source,
validate: (document) => articleSchema.parse(document),
});The injected client exposes fetch(query, params, options?); the adapter uses
a fixed parameterized GROQ query and passes an abort signal when provided.
Locale is canonicalized, slugs are validated and matched against
slug.current, and requested versions match version, _rev, _updatedAt,
or the fallback value 1. Without a requested version, lookup is unversioned.
Non-preview queries exclude drafts; preview queries may include and prefer
drafts only when the injected client's Sanity perspective allows them. The
adapter caches normalized content locally and does not create, configure, or
credential the Sanity client.