ujg-ed-l10n-modeling

name	ujg-ed-l10n-modeling
description	Generate, review, correct, and reason about Localization Modeling in User Journey Graph JSON-LD for the Editor's Draft. Use when the task is scoped to Localization module semantics for MessageBundle copy metadata and locale-switch metadata or when whole-document modeling crosses this module boundary.

UJG ED Localization Modeling

Skill tree context

Target: Editor's Draft Public spec URL: https://ujg.specs.openuji.org/ed Scope: Localization module semantics for MessageBundle copy metadata and locale-switch metadata Module scope: modules/l10n

Related generated skills:

• ujg-ed-modeling: whole UJG document modeling across Core, Graph, Surface and Experience, Runtime, Mapping, Metrics, Localization, Observability, Experience Annotation, and optional modules
• ujg-ed-core-modeling: Core module document containers, imports, top-level nodes, and extensions
• ujg-ed-graph-modeling: Graph module topology, journeys, states, transitions, exits, outgoing navigation, and indexes
• ujg-ed-observability-modeling: Observability module semantics for ObservationBinding, ObservationEvent input modality requirements, accessible-object locators, surface recognition contracts, and SurfaceInstanceResolver

When the task crosses module boundaries, read references/related-skills.md and references/skill-tree.json before continuing.

UJG ED Localization Modeling

Use this skill together with ujg-ed-modeling. Do not use it as a replacement for the parent modeling skill.

Source of truth

Use the active Editor's Draft unless the user explicitly asks for a dated snapshot:

https://ujg.specs.openuji.org/ed/modules/l10n

Generate only terms defined by the active ED Localization context unless the user explicitly requests an extension.

Scope

Localization attaches locale and copy metadata to UJG nodes.

It does not define routes, traversal, locale negotiation, runtime translation loading, ICU behavior, imports, or graph identity.

Graph defines topology. Localization annotates UJG nodes with copy and locale metadata. It can be used with Phase Step and Phase resources when the Phase context is composed, and with PainPoint only when the Experience Annotation optional module is explicitly composed.

Required context

When using Localization terms, include the Localization context:

[
  "https://ujg.specs.openuji.org/ed/ns/context.jsonld",
  "https://ujg.specs.openuji.org/ed/ns/l10n.context.jsonld"
]

When using locale switches with OutgoingTransition, also include Graph context if it is not already included.

Vocabulary

Use only these Localization classes:

MessageBundle

Use only these Localization properties:

copyRef
namespace
messageKey
defaultLocale
fallbackLocales
rtl
locales
targetLocale
l10n:targetLocale

Prefer prefixed l10n:* terms in mixed-module examples when clarity matters.

Do not invent:

locale
currentLocale
selectedLocale
translationKey
translations
messages
language
languageCode
i18n
resourceFile
bundleFormat
loader
routeLocale
localeRoute

Use private extensions only for project-specific runtime hints that are not intended to be interoperable l10n semantics.

MessageBundle

Use MessageBundle for reusable copy metadata.

A MessageBundle must have exactly one messageKey.

It may have:

namespace
defaultLocale
fallbackLocales
rtl
locales

Use locales only when embedding locale-specific payloads is useful. Otherwise prefer stable message keys and let implementation load translations externally.

Example:

{
  "@type": "l10n:MessageBundle",
  "@id": "urn:example:l10n:home-hero-title",
  "l10n:namespace": "home.hero",
  "l10n:messageKey": "home.hero.title",
  "l10n:defaultLocale": "de",
  "l10n:fallbackLocales": ["en"],
  "l10n:rtl": false
}

copyRef

Use l10n:copyRef to attach any addressable UJG node to one MessageBundle.

Example:

{
  "@type": "State",
  "@id": "urn:example:state:home-hero",
  "label": "Home hero",
  "l10n:copyRef": "urn:example:l10n:home-hero-title"
}

Do not use copyRef to define traversal, visibility, routing, state identity, component props, or runtime loading.

Locale switch affordances

Use Graph OutgoingTransition for locale switch affordances.

If the locale switch keeps the same effective graph state, use:

{
  "@type": "OutgoingTransition",
  "@id": "urn:example:ot:locale-en",
  "label": "English",
  "toCurrentState": true,
  "l10n:targetLocale": "en"
}

If the locale switch targets a distinct modeled state, use to plus l10n:targetLocale.

Do not create duplicate locale-specific states unless locale changes graph topology, available journeys, states, or affordances.

Separation rules

Keep runtime locale selection out of Localization unless the user explicitly asks for Runtime traces.

Do not model clicked language, selected language, URL locale segment, timestamp, cookie value, browser language, request header, payload, or translation-loader behavior as l10n graph metadata.

Do not use Localization to fix missing Graph structure.

Do not use targetLocale without an OutgoingTransition.

Do not use l10n:copyRef without a referenced MessageBundle.

Checks before answering

• Did I include l10n context only when l10n terms are used?
• Are all l10n terms defined by the active ED?
• Does every copyRef point to a MessageBundle?
• Does every MessageBundle have one messageKey?
• Is targetLocale used only on OutgoingTransition?
• Does a same-state locale switch use toCurrentState: true?
• Did I avoid duplicate locale states unless topology really differs?
• Did I keep runtime locale facts, loaders, URLs, and payloads out of l10n?
• Did Localization avoid changing Graph traversal?