Localization

incubating

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 .

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 MessageBundle resource through l10n:copyRef instead of hiding message keys, locale fallbacks, or locale maps inside opaque Core extensions.

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

This module is published through the following artifacts:

l10n.ttl: ontology, published at https://ujg.specs.openuji.org/ed/ns/l10n
l10n.context.jsonld: JSON-LD term mappings, published at https://ujg.specs.openuji.org/ed/ns/l10n.context.jsonld
l10n.shape.ttl: SHACL validation rules, published at https://ujg.specs.openuji.org/ed/ns/l10n.shape

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

Non-goals:

This module does not define locale negotiation, runtime translation loading, or ICU formatting behavior.
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.

3. Terminology

MessageBundle: An addressable localization resource that carries message-key and locale payload metadata.

4. Attachment Model

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

l10n:copyRef links any UJG node to a MessageBundle.

The module also defines non-reference properties such as l10n:namespace, l10n:messageKey, l10n:defaultLocale, l10n:fallbackLocales, l10n:rtl, and JSON-valued l10n:locales.

5. Ontology

The normative Localization ontology is defined below and is published at https://ujg.specs.openuji.org/ed/ns/l10n. It is the authoritative structural definition for MessageBundle and the properties declared by this module.

turtle

 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgl10n: <https://ujg.specs.openuji.org/ed/ns/l10n#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<https://ujg.specs.openuji.org/ed/ns/l10n#> a owl:Ontology ;
  rdfs:label "UJG Localization Editor's Draft Vocabulary"@en ;
  dct:description "UJG Localization ontology declaration" .

### Classes

ujgl10n:MessageBundle a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgl10n:copyRef a owl:ObjectProperty ;
  rdfs:domain ujg:Node ;
  rdfs:range ujgl10n:MessageBundle .

ujgl10n:namespace a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:messageKey a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:defaultLocale a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:fallbackLocales a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:rtl a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:boolean .

ujgl10n:locales a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range rdf:JSON . 
 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgl10n: <https://ujg.specs.openuji.org/ed/ns/l10n#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<https://ujg.specs.openuji.org/ed/ns/l10n#> a owl:Ontology ;
  rdfs:label "UJG Localization Editor's Draft Vocabulary"@en ;
  dct:description "UJG Localization ontology declaration" .

### Classes

ujgl10n:MessageBundle a owl:Class ;
  rdfs:subClassOf ujg:Node .

### Properties

ujgl10n:copyRef a owl:ObjectProperty ;
  rdfs:domain ujg:Node ;
  rdfs:range ujgl10n:MessageBundle .

ujgl10n:namespace a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:messageKey a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:defaultLocale a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:fallbackLocales a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:string .

ujgl10n:rtl a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range xsd:boolean .

ujgl10n:locales a owl:DatatypeProperty ;
  rdfs:domain ujgl10n:MessageBundle ;
  rdfs:range rdf:JSON . 

6. JSON-LD Context

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

json-ld

 {
  "@context": {
    "@version": 1.1,

    "ujgl10n": "https://ujg.specs.openuji.org/ed/ns/l10n#",
    "l10n": "https://ujg.specs.openuji.org/ed/ns/l10n#",

    "MessageBundle": "ujgl10n:MessageBundle",

    "copyRef": {
      "@id": "ujgl10n:copyRef",
      "@type": "@id"
    },
    "namespace": "ujgl10n:namespace",
    "messageKey": "ujgl10n:messageKey",
    "defaultLocale": "ujgl10n:defaultLocale",
    "fallbackLocales": {
      "@id": "ujgl10n:fallbackLocales",
      "@container": "@set"
    },
    "rtl": "ujgl10n:rtl",
    "locales": {
      "@id": "ujgl10n:locales",
      "@type": "@json"
    }
  }
} 
 {
  "@context": {
    "@version": 1.1,

    "ujgl10n": "https://ujg.specs.openuji.org/ed/ns/l10n#",
    "l10n": "https://ujg.specs.openuji.org/ed/ns/l10n#",

    "MessageBundle": "ujgl10n:MessageBundle",

    "copyRef": {
      "@id": "ujgl10n:copyRef",
      "@type": "@id"
    },
    "namespace": "ujgl10n:namespace",
    "messageKey": "ujgl10n:messageKey",
    "defaultLocale": "ujgl10n:defaultLocale",
    "fallbackLocales": {
      "@id": "ujgl10n:fallbackLocales",
      "@container": "@set"
    },
    "rtl": "ujgl10n:rtl",
    "locales": {
      "@id": "ujgl10n:locales",
      "@type": "@json"
    }
  }
} 

7. Validation

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

turtle

 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgl10n: <https://ujg.specs.openuji.org/ed/ns/l10n#> .
@prefix ujgl10nshape: <https://ujg.specs.openuji.org/ed/ns/l10n.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

ujgl10nshape:NodeCopyShape a sh:NodeShape ;
  sh:targetClass ujg:Node ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgl10n:copyRef ;
    sh:class ujgl10n:MessageBundle ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] .

ujgl10nshape:MessageBundleShape a sh:NodeShape ;
  sh:targetClass ujgl10n:MessageBundle ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgl10n:namespace ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:messageKey ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:defaultLocale ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:fallbackLocales ;
    sh:datatype xsd:string ;
  ] ;

  sh:property [
    sh:path ujgl10n:rtl ;
    sh:datatype xsd:boolean ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:locales ;
    sh:datatype rdf:JSON ;
    sh:maxCount 1 ;
  ] . 
 @prefix ujg: <https://ujg.specs.openuji.org/ed/ns/core#> .
@prefix ujgl10n: <https://ujg.specs.openuji.org/ed/ns/l10n#> .
@prefix ujgl10nshape: <https://ujg.specs.openuji.org/ed/ns/l10n.shape#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

ujgl10nshape:NodeCopyShape a sh:NodeShape ;
  sh:targetClass ujg:Node ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgl10n:copyRef ;
    sh:class ujgl10n:MessageBundle ;
    sh:nodeKind sh:IRI ;
    sh:maxCount 1 ;
  ] .

ujgl10nshape:MessageBundleShape a sh:NodeShape ;
  sh:targetClass ujgl10n:MessageBundle ;
  sh:nodeKind sh:IRI ;

  sh:property [
    sh:path ujgl10n:namespace ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:messageKey ;
    sh:datatype xsd:string ;
    sh:minCount 1 ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:defaultLocale ;
    sh:datatype xsd:string ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:fallbackLocales ;
    sh:datatype xsd:string ;
  ] ;

  sh:property [
    sh:path ujgl10n:rtl ;
    sh:datatype xsd:boolean ;
    sh:maxCount 1 ;
  ] ;

  sh:property [
    sh:path ujgl10n:locales ;
    sh:datatype rdf:JSON ;
    sh:maxCount 1 ;
  ] . 

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

Attachment only: Localization properties MUST NOT change Graph validity, graph traversal behavior, import resolution, or core node identity.
Bundle semantics: l10n:messageKey identifies the canonical message entry for the attached node, while l10n:locales carries optional locale-specific payloads for implementations that choose to embed translated values.
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.
Private runtime hints: Platform-specific i18n loader configuration that is not intended for shared queryability or validation SHOULD remain in Core extensions.

8. Appendix: Combined JSON Example

json

 {
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/l10n.context.jsonld"
  ],
  "@id": "https://example.com/ujg/l10n/checkout.jsonld",
  "@type": "UJGDocument",
  "specVersion": "1.0",
  "nodes": [
    {
      "@type": "ExperienceStep",
      "@id": "urn:ujg:step:order-confirmation",
      "label": "Order confirmation",
      "l10n:copyRef": "urn:l10n:bundle:order-confirmation"
    },
    {
      "@type": "l10n:MessageBundle",
      "@id": "urn:l10n:bundle:order-confirmation",
      "l10n:namespace": "checkout.confirmation",
      "l10n:messageKey": "order.confirmation.title",
      "l10n:defaultLocale": "en",
      "l10n:fallbackLocales": ["en", "de"],
      "l10n:rtl": false,
      "l10n:locales": {
        "en": {
          "title": "Order confirmed",
          "subtitle": "Your receipt is on the way."
        },
        "de": {
          "title": "Bestellung bestaetigt",
          "subtitle": "Ihre Quittung ist unterwegs."
        }
      }
    }
  ]
} 
 {
  "@context": [
    "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
    "https://ujg.specs.openuji.org/ed/ns/l10n.context.jsonld"
  ],
  "@id": "https://example.com/ujg/l10n/checkout.jsonld",
  "@type": "UJGDocument",
  "specVersion": "1.0",
  "nodes": [
    {
      "@type": "ExperienceStep",
      "@id": "urn:ujg:step:order-confirmation",
      "label": "Order confirmation",
      "l10n:copyRef": "urn:l10n:bundle:order-confirmation"
    },
    {
      "@type": "l10n:MessageBundle",
      "@id": "urn:l10n:bundle:order-confirmation",
      "l10n:namespace": "checkout.confirmation",
      "l10n:messageKey": "order.confirmation.title",
      "l10n:defaultLocale": "en",
      "l10n:fallbackLocales": ["en", "de"],
      "l10n:rtl": false,
      "l10n:locales": {
        "en": {
          "title": "Order confirmed",
          "subtitle": "Your receipt is on the way."
        },
        "de": {
          "title": "Bestellung bestaetigt",
          "subtitle": "Ihre Quittung ist unterwegs."
        }
      }
    }
  ]
} 

9. Appendix: Opaque Runtime Hints

json

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