UJG / UJG 1.0 Release Candidate 3 /
W3C Community Group Draft Report

Localization

draft

Status of this Document

This report was published by the User Journey Graph Community Group . It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups .

Status
CG-DRAFT
Version
1.0-rc3
Published
2026-11-09
Last Update
2026-11-09
Editors
  • Seva Dolgopolov
Group
User Journey Graph Community Group
Repository
View Source
License
W3C-Software-and-Document

1. Overview

This optional module defines a graph-native vocabulary for attaching localization metadata to UJG nodes. It lets a producer bind any addressable node to a reusable MessageMeta resource through l10n:copyRef, and model concrete locale-specific text as addressable Message nodes.

This module is optional. Its properties annotate Graph resources and do not themselves change topology, traversal rules, or import resolution. A producer may nevertheless model different Graph Journeys, States, or affordances when content structure genuinely differs by locale; Graph owns those topology differences.

2. Terminology

  • Locale: An addressable locale resource identified by a language tag.

  • MessageMeta: An addressable message identity and shared metadata resource.

  • Message: An addressable locale-specific value for one MessageMeta and one Locale.

3. Locale

A Locale identifies one locale used by localization metadata or locale-specific messages.

classDiagram
  class Locale {
    id
    localeCode
  }

Example JSON node:

json 
{
  "@type": "l10n:Locale",
  "@id": "urn:l10n:locale:en",
  "l10n:localeCode": "en"
}
{
  "@type": "l10n:Locale",
  "@id": "urn:l10n:locale:en",
  "l10n:localeCode": "en"
}

4. MessageMeta

A MessageMeta identifies a reusable copy contract. The MessageMeta IRI is the stable message identity. UJG nodes reference a message meta node with l10n:copyRef.

classDiagram
  class Locale
  class MessageMeta {
    id
    argumentNames
    defaultLocaleRef
    fallbackLocaleRefs
    rtl
  }
  MessageMeta --> Locale : defaultLocaleRef
  MessageMeta --> "0..*" Locale : fallbackLocaleRefs

Example JSON node:

json 
{
  "@type": "l10n:MessageMeta",
  "@id": "urn:l10n:message-meta:order-confirmation-title",
  "l10n:argumentNames": ["orderNumber"],
  "l10n:defaultLocaleRef": "urn:l10n:locale:en",
  "l10n:fallbackLocaleRefs": ["urn:l10n:locale:en", "urn:l10n:locale:de"],
  "l10n:rtl": false
}
{
  "@type": "l10n:MessageMeta",
  "@id": "urn:l10n:message-meta:order-confirmation-title",
  "l10n:argumentNames": ["orderNumber"],
  "l10n:defaultLocaleRef": "urn:l10n:locale:en",
  "l10n:fallbackLocaleRefs": ["urn:l10n:locale:en", "urn:l10n:locale:de"],
  "l10n:rtl": false
}

5. Message

A Message carries one locale-specific string value for one MessageMeta and one Locale. The value is an opaque string from the perspective of Localization conformance.

classDiagram
  class MessageMeta
  class Locale
  class Message {
    id
    messageMetaRef
    localeRef
    value
  }
  Message --> MessageMeta : messageMetaRef
  Message --> Locale : localeRef

Example JSON node:

json 
{
  "@type": "l10n:Message",
  "@id": "urn:l10n:message:order-confirmation-title:en",
  "l10n:messageMetaRef": "urn:l10n:message-meta:order-confirmation-title",
  "l10n:localeRef": "urn:l10n:locale:en",
  "l10n:value": "Order ${orderNumber} confirmed"
}
{
  "@type": "l10n:Message",
  "@id": "urn:l10n:message:order-confirmation-title:en",
  "l10n:messageMetaRef": "urn:l10n:message-meta:order-confirmation-title",
  "l10n:localeRef": "urn:l10n:locale:en",
  "l10n:value": "Order ${orderNumber} confirmed"
}

6. Attachment Model

The module introduces real JSON-LD terms and RDF edges for localization attachment:

  • l10n:copyRef links any UJG node to a MessageMeta.

  • l10n:messageMetaRef links a Message to the MessageMeta it realizes.

  • l10n:localeRef links a Message to its Locale.

  • l10n:defaultLocaleRef and l10n:fallbackLocaleRefs link MessageMeta to fallback locale resources.

  • l10n:targetLocaleRef declares the requested Locale associated with an OutgoingTransition.

classDiagram
  class Node {
    copyRef
  }
  class MessageMeta
  class Locale
  class OutgoingTransition {
    targetLocaleRef
  }
  Node --> MessageMeta : copyRef
  OutgoingTransition --> Locale : targetLocaleRef

Example JSON nodes:

Here the locale switch explicitly re-enters the same Journey and State through its entry contract. Localization supplies the requested locale; Graph supplies the destination.

The module also defines non-reference properties l10n:localeCode, l10n:argumentNames, l10n:rtl, and l10n:value.

7. Normative Artifacts

This module is published through the following artifacts:

  • l10n.ttl: ontology, published at https://ujg.specs.openuji.org/tr/1.0-rc3/ns/l10n

  • l10n.context.jsonld: JSON-LD term mappings, published at https://ujg.specs.openuji.org/tr/1.0-rc3/ns/l10n.context.jsonld

  • l10n.shape.ttl: SHACL validation rules, published at https://ujg.specs.openuji.org/tr/1.0-rc3/ns/l10n.shape

Examples in this page compose the shared baseline context https://ujg.specs.openuji.org/tr/1.0-rc3/ns/context.jsonld with the Localization context.

Non-goals:

  • This module does not define locale negotiation, runtime translation loading, JavaScript evaluation, ICU formatting behavior, pluralization, or runtime interpolation APIs.

  • This module does not introduce new traversal semantics beyond [UJG Graph].

  • This module does not replace opaque vendor-private hints carried in [UJG Core] extensions.

7.1. Ontology

The normative Localization ontology is defined below and is published at https://ujg.specs.openuji.org/tr/1.0-rc3/ns/l10n. It is the authoritative structural definition for Locale, MessageMeta, Message, and the properties declared by this module.

7.2. JSON-LD Context

The normative Localization JSON-LD context is defined below and is published at https://ujg.specs.openuji.org/tr/1.0-rc3/ns/l10n.context.jsonld. It provides the compact JSON-LD term mappings and coercions for Localization-specific properties and classes.

7.3. Validation

The normative Localization SHACL shape is defined below and is published at https://ujg.specs.openuji.org/tr/1.0-rc3/ns/l10n.shape. It is the authoritative validation artifact for Localization structural constraints.

The rules below define the remaining module semantics beyond the structural constraints captured by the SHACL shape.

  1. Attachment only: Localization properties MUST NOT change Graph validity, graph traversal behavior, import resolution, or core node identity. Locale-dependent topology MAY be modeled explicitly with distinct Graph Journeys, Entries, States, and Transitions.

  2. Message identity: A MessageMeta IRI identifies the reusable message contract. Producers MUST use that IRI as the shared message identity.

  3. Locale identity: Locale references use Locale IRIs. A Locale.localeCode value identifies the language tag represented by that locale resource.

  4. Message uniqueness: Producers MUST NOT create more than one Message for the same messageMetaRef and localeRef pair.

  5. Opaque value: Message.value is a string value. Consumers MUST NOT infer UJG graph edges, message dependencies, JavaScript execution, ICU behavior, or cycle constraints from the string.

  6. Locale target metadata: l10n:targetLocaleRef declares the requested locale associated with an outgoing affordance. It does not itself define graph traversal behavior. The host OutgoingTransition's toEntryRef selects the destination JourneyEntry.

  7. Shared-topology state preservation: When a locale switch must preserve whichever of several States is active, each source State MUST directly reference a state-specific OutgoingTransition. Each transition's toEntryRef MUST target the JourneyEntry for the corresponding destination State.

  8. Fixed group destinations: An OutgoingTransitionGroup MAY contain a locale switch only when its one fixed destination entry is correct for every effective source. Consumers MUST NOT reinterpret a grouped transition's toEntryRef as relative to the active State.

  9. Locale topology: When locales share topology, a state-scoped locale-switch OutgoingTransition may target an entry whose stateRef is the same State where that affordance is available. When content structure differs by locale, it may target an entry owned by a locale-specific Journey with different local topology.

  10. No locale inference: Consumers MUST NOT infer a Journey, JourneyEntry, or State from targetLocaleRef; the Graph reference remains explicit and authoritative.

  11. Graceful degradation: A consumer that does not implement this module MAY ignore Localization semantics, but it SHOULD preserve recognized JSON-LD data during read-transform-write when possible.

  12. Private runtime hints: Platform-specific i18n loader configuration that is not intended for shared queryability or validation SHOULD remain in Core extensions.

8. Examples

8.1. Shared-Topology State-Preserving Switches

A state-preserving switch is source-specific because each OutgoingTransition has one fixed toEntryRef. In this shared-topology checkout Journey, switching to English from Form re-enters Form, while switching from Success re-enters Success:

The two locale-switch affordances may look identical in the interface, but they are different Graph edges with different destination entries. A Journey-level OutgoingTransitionGroup would be wrong for this state-preserving behavior: it would inject one transition with one fixed entry into both States. A group remains appropriate when every source intentionally enters the same locale landing entry.

8.2. Locale Switch Affordance Example

The English Journey has one confirmation State. The German Journey has a summary followed by a separate legal-notice State. The locale switch therefore targets the German entry contract rather than assuming that both locales share a State or topology.

8.3. Combined JSON Example

8.4. Opaque Runtime Hints

json 
{
  "@id": "urn:l10n:message-meta:order-confirmation-title",
  "@type": "l10n:MessageMeta",
  "extensions": {
    "com.acme.i18n-runtime": {
      "resourceFile": "checkout/confirmation.json",
      "bundleFormat": "icu"
    }
  }
}
{
  "@id": "urn:l10n:message-meta:order-confirmation-title",
  "@type": "l10n:MessageMeta",
  "extensions": {
    "com.acme.i18n-runtime": {
      "resourceFile": "checkout/confirmation.json",
      "bundleFormat": "icu"
    }
  }
}