Locale i18n framework

3 min readReferenceUpdated 2026-05-19

What you'll find here

How locale preferences, translatable documents, and resolution work together to keep runtime identifiers stable while operator-facing text follows locale chains and fallbacks.

Runtime ids stay language-neutral.

Translation may change operator-facing prose, but schema names, ids, receipt ids, policy envelope ids, evidence ids, memory entities, and task ids remain language-neutral.

Locale preferences

LocalePreference records:

Preferred locale

Fallback locales

Default locale

Fallback strategy

Optional formatting locale

Fallback strategies

Strategy

Resolution order

Notes

exact_then_language

full → language → fallbacks → default

Try the full locale, then the language subtag, then configured fallbacks and default.

exact_then_default

full → fallbacks → default

Skip language-subtag step.

default_only

full → default

Skip user fallbacks entirely.

Translatable docs

TranslatableDocMetadata records a stable language-neutral id, source path, source locale, available locales, translated paths, policy envelope, evidence, receipts, and redaction requirements.

Resolution

resolve_doc_locale returns a LocaleResolution with:

Requested locale

Resolved locale

Status

source · translated · fallback · missing.

Resolved path

Fallback chain

Policy · evidence · receipt · redaction metadata

Always public-safe.

When a translation is unavailable, Craik falls back to the configured chain and ultimately the source document. Public docs and translated exports must continue to avoid credentials, private local paths, and private task names.

Boundaries

Locale support preserves:

Policy decisions

And envelope references.

Evidence & receipt links

Redaction markers

And secret references.

Stable runtime identifiers

Formatting boundaries

For dates, numbers, locale-specific display text.

Translation review receipts record the source document, translated locale, reviewer or automation evidence, and confirmation that policy and redaction semantics were preserved.

What's next

GuideTranslated documentation strategyThe author-facing rules.ReferenceSchema referenceWhere translatable-doc metadata sits in the contract catalog.ReferencePublic boundaryWhat translated docs must not expose.