ujg-ed-l10n-modeling

name	ujg-ed-l10n-modeling
description	Generate, review, and correct UJG ED Localization JSON-LD. Use when attaching MessageBundle copy metadata or locale-switch metadata through l10n terms without changing Graph topology.

---

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 graph or experience resources with copy and locale metadata.

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?