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

Localization

draft

Status of this Document

This report was published by the User Journal 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-rc1
Published
2026-07-27
Last Update
2026-07-27
Editors
  • Seva Dolgopolov
Group
User Journal 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. It annotates the shared graph with localization resources, but it does not change graph topology, traversal rules, or import resolution.

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:

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/ns/l10n

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

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

Examples in this page compose the shared baseline context https://ujg.specs.openuji.org/tr/1.0/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/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/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/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.

  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. If a locale switch should keep the user on the same graph state, use Graph's toCurrentState: true together with l10n:targetLocaleRef.

  7. 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.

  8. 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. Locale Switch Affordance Example

8.2. Combined JSON Example

8.3. 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"
    }
  }
}