Resolved on read

A read says which locale and context it wants and whether it wants the draft. The server does the choosing, and each client receives the finished values on the fields it asked for.

Three arguments on every read

Every per-model read, singular or list, takes three arguments: locale, contexts and preview. The resolved values come back directly on the typed fields. The typed SDK takes the same three on its own calls.

Locale fallback, field by field

For each translatable field the server walks an ordered list and serves the first value it finds: the requested locale, its configured fallback chain, the closest matches in the same language and script, the project default, then the authored value. Because the walk is per field, a partly translated record can return its title from one locale and its body from another in the same response. A read that names no locale gets the authored values.

Variants and audience

The contexts argument carries targeting dimensions. Device, platform and locale are built in, and your project's own dimensions, a market for example, are typed as enums. The server derives sign-in status and segment membership from the signed-in user's access token. It then selects the matching variant and merges its values onto the record. A dimension you leave out is absent, so a rule that requires it does not match.

Draft or published

With preview set to true, a read returns the latest draft in place of the published version, for a key that holds the drafts:read scope.

Checking how a read resolved

Two debugging switches report on a read without changing its content. localeStrict lists the fields that fell back. resolutionTrace returns the full walk, to a key that holds the targeting debug scope.

Read the detail

The GraphQL guide documents the locale, contexts and preview arguments and what each one resolves.