OpenWOP openwop.dev

Status: Stable.

Normative home: i18n, content.

Why this exists

A client asks for a locale for human-facing text (interrupt prompts, error messages, extension UI strings) and the host answers with the one it used. Identifiers stay ASCII and timestamps ISO 8601; number, currency and text-direction formatting are out of scope.

Language tags

Every locale identifier — Accept-Language, Content-Language and every locale field — is a BCP 47 tag.

  • Tags compare case-insensitively (RFC 5646 §2.1.1, RFC 4647 §2).
  • A host SHOULD advertise and emit tags in the case RFC 5646 §2.1.1 recommends: lowercase language, titlecase script, uppercase region (zh-Hant-TW, es-419).

Accept-Language

A client MAY send Accept-Language (RFC 9110 §12.5.4) on any request. A host MAY honor it to localize human-facing text in the response.

A host:

  • MUST parse the header without failing the request. A malformed value MUST NOT cause 400; the host proceeds in its default locale.
  • MUST NOT reject a request because it does not support the requested locale.
  • MUST honor q-values: the highest-q locale it supports wins, and ties go to request order.
  • MUST NOT infer a locale from the request body to override the header, which is authoritative.
  • SHOULD set Content-Language to the canonical tag of the locale used when it localized the response. When it localized nothing, it SHOULD omit Content-Language or set it to its default locale.
  • MAY cache localized text. When localization is expensive, caching by (localeTag, sourceText) is RECOMMENDED.
  • MAY return default-locale text at once and emit node.completed when the localized version is ready.

Fallback

When a host cannot localize to the requested locale, it:

  1. walks the list in q-value order and uses the first locale it supports;
  2. otherwise tries the language family (ja for ja-JP, sending Content-Language: ja);
  3. otherwise uses its default locale, which it SHOULD advertise as i18n.defaultLocale;
  4. sets Content-Language to the locale it actually used, never another.

Error envelopes

A host MAY localize an error message, and MAY then add details.locale.

  • The error code MUST be the same registered identifier in every locale (errors.md); it is never translated.
  • details keys are schema field names and are not localized.
  • A human-facing details value MAY be localized, and SHOULD carry a locale sibling on the same object.

The i18n record

A host that negotiates locale SHOULD advertise i18n. A host advertising it honors Accept-Language on every protected route; a host that omits it serves one locale, its default, and ignores the header.

  • defaultLocale — the locale returned when no Accept-Language entry matches supportedLocales; "en" when omitted.
  • supportedLocales — the locales the host can return for human-facing text. It MUST contain defaultLocale, and its order carries no meaning.
  • A host that translates by machine SHOULD list only the locales it has validated end to end.

Replay and fork

Locale is chosen at request time. Content-Language is request-scoped and not recorded in the event log, so a replay re-projects the recorded text and does not re-render it. A fork localizes by its own request's Accept-Language, not the parent run's.

Localized content

A host advertising content serves authored pages (schemas/v2/localized-content-.schema.json) on the /content/ operations. A section is one record, base data plus sparse localizations, never one record per locale.

  • Advertisement. A host advertising content MUST advertise i18n, with content.baseLocale equal to i18n.defaultLocale and every locale in baseLocale ∪ supportedLocales also in i18n.supportedLocales. It SHOULD advertise only locales it delivers, in the case §Language tags recommends.
  • Delivery. Locale is negotiated only by Accept-Language (§Fallback); there is no ?locale= parameter. A section negotiated to baseLocale resolves to data. Any other section resolves to data shallowly overlaid by the first localizations entry for the exact tag, its ll-Ssss script family, or its language, else to data alone. Every host MUST resolve identically.
  • Writes. A write names its locale in the body: baseLocale upserts data, and any other locale upserts its overlay.
  • Publication is atomic across locales. Public delivery MUST serve published content only and MUST NOT cache a draft in a shared entry.
  • Tenancy. Every read and write MUST be tenant-scoped, and another tenant's id MUST get the same 404 as a missing one. Anonymous tenant resolution is host-defined, so identical resolution holds per resolved (tenant, locale).

Clients

A client that wants localized content MUST check discovery for i18n before sending Accept-Language.

Sources: RFCs 0103, 0206.

Keep reading.

Edit this page on GitHub ↗

  • ErrorsEvery error a v2 host returns is a row in one registry. A client routes on error, never…
  • Form Content PacksA form-content pack ships declarative form templates a host renders in its own chrome.…
  • OpenWOP v2 Core — Overviewspec/v2/core/ is what a host implements to pass the 2.0.0 floor: reading order, the six…