Skip to main content
Version: MVP

Translated documentation strategy

4 min readFor maintainersUpdated 2026-05-19

What you'll find here

How Craik handles localized docs. Translations are presentation surfaces over the English source-of-truth pages. They never redefine policy, evidence, receipt, redaction, schema, or identifier semantics.

Presentation, not policy.

If a translation cannot preserve the meaning of a policy rule, schema field, receipt status, or redaction requirement, the translated page remains deferred and links back to the source page.

Source of truth​

Canonical documentation lives under docs/ and is authored as the source locale for each page. Translated pages may live in locale-specific paths when reviewed and linked through metadata described in Locale i18n framework.

Source-of-truth pages define:

Stable language-neutral document ids

Canonical links

To contracts and guides.

Policy · evidence · receipt · redaction semantics

Public boundary requirements

Fallback path

When a translation is unavailable.

Translation metadata​

Each translatable page records:

Field
Required
Purpose
Stable document id
always
Language-neutral identity.
Source path and source locale
always
Canonical reference.
Available locales and translated paths
always
Resolved at link time.
Policy envelope id
always
Governs translation review.
Evidence references
always
For source material and review.
Receipt references
always
For translation checks.
Redaction requirement
always
Applied to both source and translated pages.
Identifier-neutrality confirmation
always
Runtime identifiers remain language-neutral.

This metadata is represented by TranslatableDocMetadata and resolved through resolve_doc_locale. The resolution result records the requested locale, resolved locale, fallback chain, path, and policy/evidence/receipt context.

Translated docs include a path back to the source page when a locale is incomplete, stale, community-maintained, or deferred.

  1. Exact locale.
  2. Language-only locale when configured.
  3. Configured fallback locales.
  4. Source locale.

Fallback links go to public pages only.

Never expose local filesystem paths, private planning labels, credentials, or private task names through fallback link resolution.

Review expectations​

  1. Public boundary language is preserved.
  2. Redaction markers and secret references are not translated into secret values.
  3. Schema names, ids, receipt ids, policy ids, memory entities, and task ids are unchanged.
  4. Code blocks and CLI commands remain technically valid.
  5. Links resolve through docs tests or documented deferred status.
  6. Any machine-generated translation has human or policy review before being marked supported.

Review receipts record the source page, target locale, review evidence, reviewer or automation id, and whether policy/evidence/receipt/redaction semantics were preserved.

Deferred and community-maintained translations​

Deferred

No reviewer · terminology unsettled · source docs changing too quickly. Deferred translations use fallback links rather than stale translated prose.

Community-maintained

Acceptable when following the same metadata, review, public-boundary, and receipt expectations. Community status must be visible in the metadata or review receipt. Source docs remain authoritative when conflicts appear.

Limits​

Translations must NOT.

Translate runtime identifiers

Or schema names.

Weaken policy / approval / grant / receipt / evidence / redaction

Introduce examples

With real credentials, private paths, or private task names.

Imply unsupported behavior

Locale-specific behavior that does not exist in the runtime.

Bypass docs link validation

Except through explicitly documented deferred status.

What's next​

ReferenceLocale i18n frameworkMetadata, resolution contracts, and the shipped TranslationStatus values.ReadLimitationsWhy translation rollout follows roadmap milestones.