@_linked/translation 0.6.0 → 0.8.0

package/src/archive.ts

@@ -26,8 +26,8 @@ export const TRANSLATION_ARCHIVE_MANIFEST_PATH =
   'linked.translation-archive.json';
 
 /**
- * Archives written before 0.3.0 named the manifest — and the archive format
- * itself — after Create Now. Both spellings are read; only the current one is
+ * Archives written before 0.3.0 used the pre-0.3.0 spelling for the manifest
+ * and the archive format. Both spellings are read; only the current one is
  * written. The format id is inside `archiveContentHash`'s input, so a legacy
  * manifest keeps the value it was hashed with.
  */

package/src/authorization.ts

@@ -20,7 +20,7 @@ let resolver: TranslationAuthorizationResolver | undefined;
 
 /**
  * Host hook: the host decides who may read and author an app's translations
- * (Create Now evaluates its translator assignments and project roles here).
+ * (for example by evaluating its own translator assignments and project roles).
  *
  * The resolver is the only source of a "yes". A host that does not configure
  * one gets no authoring or read access over the translation provider; only the

package/src/cdn-loader.ts

@@ -13,7 +13,7 @@ import {
  * Any source that yields a non-empty map wins; all-empty ⇒ `{}` and the client
  * keeps its inline English defaults. Never throws.
  *
- * Portable (no CN import): the caller wires `base`/`devApi` for its environment.
+ * Portable (no host-application import): the caller wires `base`/`devApi` for its environment.
  */
 import type { TranslationMessages } from './core/messages.js';
 import { sha256Hex } from './key-version.js';

package/src/core/messages.ts

@@ -26,6 +26,36 @@ export type TranslationMessage = string | FormattedTranslationMessage;
 /** key → message template, for a single language. */
 export type TranslationMessages = Record<string, TranslationMessage>;
 
+/**
+ * Development pseudo-locale used by chrome coverage checks. Keeping this in
+ * the framework-light core means React and non-React clients exercise the
+ * exact same fallback path. The wrapper makes missed layout allowance visible;
+ * the accented glyphs make an untranslated English fallback unmistakable.
+ */
+export function pseudoLocalize(message: string): string {
+  const accents: Record<string, string> = {
+    A: 'Å', B: 'Ɓ', C: 'Ç', D: 'Ð', E: 'Ë', F: 'Ƒ', G: 'Ĝ', H: 'Ĥ', I: 'Ï',
+    J: 'Ĵ', K: 'Ķ', L: 'Ļ', M: 'Ṁ', N: 'Ñ', O: 'Ö', P: 'Ƥ', Q: 'Ǫ', R: 'Ŕ',
+    S: 'Š', T: 'Ŧ', U: 'Ü', V: 'Ṽ', W: 'Ŵ', X: 'Ẍ', Y: 'Ŷ', Z: 'Ž',
+    a: 'å', b: 'ƀ', c: 'ç', d: 'đ', e: 'ë', f: 'ƒ', g: 'ĝ', h: 'ĥ', i: 'ï',
+    j: 'ĵ', k: 'ķ', l: 'ļ', m: 'ṁ', n: 'ñ', o: 'ö', p: 'ƥ', q: 'ǫ', r: 'ŕ',
+    s: 'š', t: 'ŧ', u: 'ü', v: 'ṽ', w: 'ŵ', x: 'ẍ', y: 'ŷ', z: 'ž',
+  };
+  const accented = message.replace(/[A-Za-z]/g, (character) => accents[character]);
+  return `［${accented} ···］`;
+}
+
+/**
+ * Layout-stress pseudo mode. Unlike en-XA's accented fallback, this deliberately
+ * expands the resolved message—including a real translated catalog value—so a
+ * preview can expose controls that only fit their English copy.
+ */
+export function pseudoExpand(message: string): string {
+  const visibleLength = [...message].length;
+  const padding = '·'.repeat(Math.max(3, Math.ceil(visibleLength * 0.35)));
+  return `［${message} ${padding}］`;
+}
+
 /** FormatSimple: replace `{name}` placeholders with `params.name`. Unknown → left as-is. */
 export function interpolate(
   template: string,
@@ -59,7 +89,7 @@ function compiledIcu(template: string, locale: string): IntlMessageFormat {
 /**
  * Full ICU MessageFormat using the active locale's CLDR plural rules. Invalid
  * authoring data never crashes the host app: the unformatted template remains
- * visible and Translation Studio reports the syntax error for repair.
+ * visible and authoring tools can report the syntax error for repair.
  */
 export function formatIcu(
   template: string,
@@ -93,9 +123,12 @@ export function translate(
       : stored?.message ?? defaultValue ?? key;
   const resolvedFormat =
     typeof stored === 'object' ? stored.format : format;
-  return resolvedFormat === 'icu'
+  const formatted = resolvedFormat === 'icu'
     ? formatIcu(template, params, locale)
     : interpolate(template, params);
+  return stored === undefined && locale.toLowerCase() === 'en-xa'
+    ? pseudoLocalize(formatted)
+    : formatted;
 }
 
 /** @deprecated Use directionFor; this historical set is not a support boundary. */

package/src/exchange.ts

@@ -363,7 +363,7 @@ export function normalizeParsedTranslationExchangeDocument(
   };
 }
 
-/** Validate the stronger, version-evidenced document required for CN exports. */
+/** Validate the stronger, version-evidenced document this package's own exports carry. */
 export function validateTranslationExchangeDocument(
   value: unknown,
 ): TranslationExchangeDocument {

package/src/export.ts

@@ -95,7 +95,10 @@ export async function createTranslationExchangeDocument(
       key: entry.key,
       namespace: entry.namespace,
       kind:
-        entry.ofShape || entry.ofProperty || entry.fromPackage
+        entry.ofShape ||
+        entry.ofProperty ||
+        entry.ofResource ||
+        entry.fromPackage
           ? 'semantic'
           : 'ui',
       sourceText: version.sourceText,

package/src/formats/xliff.ts

@@ -14,7 +14,7 @@ const UTF8 = new TextEncoder();
  * Our own XML metadata namespace for exchange files. It is a file-format
  * identifier written into exported documents, not the translation ontology
  * (which lives at `https://linked.cm/ont/translation/`). Files exported before 0.3.0
- * used a Create Now URI and a `cn:` prefix; the reader below still accepts
+ * used the pre-0.3.0 namespace URI and prefix; the reader below still accepts
  * both, so those files keep importing.
  */
 const EXCHANGE_NAMESPACE = 'https://id.linked.cm/translation/exchange/1';

package/src/key-sync.ts

@@ -12,7 +12,18 @@ export interface ExtractedTranslationKey {
 }
 
 export interface TranslationKeySyncTarget {
-  list(data: { appId: string }): Promise<Array<{ key: string; sourceText?: string }>>;
+  /**
+   * Existing keys. `overridden: true` marks a declared key the app has reworded
+   * locally; sync reports it in `preservedOverrides` and never writes it.
+   */
+  list(data: { appId: string }): Promise<
+    Array<{ key: string; sourceText?: string; overridden?: boolean }>
+  >;
+  /**
+   * Write one key. A writer that keeps an app override instead of applying the
+   * declared source answers `{ preservedOverride: true }` (see
+   * `upsertTranslationKey` with `source: 'declaration-sync'`).
+   */
   upsert(data: {
     appId: string;
     key: string;
@@ -25,6 +36,8 @@ export interface TranslationKeySyncReport {
   created: string[];
   updated: string[];
   unchanged: string[];
+  /** Keys whose app override was kept over the declared source; also in `unchanged`. */
+  preservedOverrides: string[];
   orphaned: string[];
   conflicts: Array<{ key: string; defaults: string[] }>;
 }
@@ -141,7 +154,12 @@ export async function syncTranslationKeys(
     defaultsByKey.set(item.key, defaults);
   }
   const report: TranslationKeySyncReport = {
-    created: [], updated: [], unchanged: [], orphaned: [], conflicts: [],
+    created: [],
+    updated: [],
+    unchanged: [],
+    preservedOverrides: [],
+    orphaned: [],
+    conflicts: [],
   };
   for (const [key, defaults] of defaultsByKey) {
     if (defaults.size > 1) {
@@ -150,15 +168,37 @@ export async function syncTranslationKeys(
     }
     const sourceText = [...defaults][0];
     const current = existingByKey.get(key);
-    if (!current) report.created.push(key);
-    else if (current.sourceText !== sourceText) report.updated.push(key);
-    else {
+    if (current?.overridden === true) {
+      report.preservedOverrides.push(key);
+      report.unchanged.push(key);
+      continue;
+    }
+    if (current?.sourceText === sourceText) {
       report.unchanged.push(key);
       continue;
     }
     if (!options.dryRun) {
-      await target.upsert({ appId, key, sourceText, kind: 'ui' });
+      const result = await target.upsert({
+        appId,
+        key,
+        sourceText,
+        kind: 'ui',
+      });
+      // The writer is authoritative: an override may have appeared since list,
+      // or the portable target may not project ownership in its list response.
+      if (
+        result &&
+        typeof result === 'object' &&
+        'preservedOverride' in result &&
+        result.preservedOverride === true
+      ) {
+        report.preservedOverrides.push(key);
+        report.unchanged.push(key);
+        continue;
+      }
     }
+    if (current) report.updated.push(key);
+    else report.created.push(key);
   }
   report.orphaned = existing
     .map((item) => item.key)

package/src/mt.ts

@@ -5,7 +5,7 @@
  * with a fallback chain: not every provider covers every language (DeepL has
  * no Swahili or Urdu), so the preferred provider is used where it supports
  * the target and the chain falls through otherwise. Pure module: no I/O, no
- * SDK imports — concrete providers live with the host (Create Now) and are
+ * SDK imports — concrete providers live with the host application and are
  * registered at boot.
  */
 import {

package/src/ontologies/translation.ts

@@ -12,7 +12,7 @@ export var loadData = () => {
  * Public ontology namespace for the translation package. First-party Linked
  * ontologies live at `https://linked.cm/ont/{ontologySlug}/{localName}`, where
  * the ontology slug — and the prefix label — is the package's public slug
- * (Create Now arch-02, "Public ontology namespace"). So terms are
+ * (the LINKED first-party ontology namespace rule). So terms are
  * `https://linked.cm/ont/translation/TranslationKey` and the prefix is
  * `translation:`. Before 0.5.0 this was `https://id.linked.cm/translation/vocab#`.
  */
@@ -51,6 +51,7 @@ export var ofNode = ns('ofNode'); // content-translation subject (kind:'content'
 export var ofField = ns('ofField');
 export var ofShape = ns('ofShape'); // semantic SHACL shape context for package keys
 export var ofProperty = ns('ofProperty'); // semantic predicate context for package keys
+export var ofResource = ns('ofResource'); // arbitrary semantic resource (action, group, condition, port)
 export var fromPackage = ns('fromPackage'); // package that supplied a seed catalog
 export var overridden = ns('overridden'); // app diverged this shape key from canonical → excluded from shape propagation (AD-N)
 export var shapeSource = ns('shapeSource'); // canonical source snapshot at override time → the value "clear override" reverts to (AD-N)
@@ -78,7 +79,7 @@ export var publishedAt = ns('publishedAt');
 export var supportedUntil = ns('supportedUntil');
 export var qualitySummary = ns('qualitySummary');
 
-// ── CapabilityAppConfig properties (stored in Create Now's cn-main) ────
+// ── CapabilityAppConfig properties (stored in the host's app configuration) ────
 export var languages = ns('languages'); // active BCP-47 tags, including source
 export var defaultLanguage = ns('defaultLanguage'); // authored/source language
 export var cdnTarget = ns('cdnTarget'); // delivery base URL / bucket prefix — the "repoint" knob (AD-K, P2)
@@ -167,6 +168,7 @@ export const tr = {
   ofField,
   ofShape,
   ofProperty,
+  ofResource,
   fromPackage,
   overridden,
   shapeSource,

package/src/package.ts

@@ -1,11 +1,8 @@
 import { linkedPackage } from '@_linked/core/utils/Package';
 
-// Reusable LINKED translation package. Uses a HOST-NEUTRAL identifier root
-// (NOT CN's id.create.now), so the shape/ontology IRIs baked into every app's
-// dataset stay stable when this package is later extracted to its own repo
-// (`@_linked/translation` / `@semantu/translation`) — a move, not a rewrite
-// (Plan 014 AD-G). R14: confirm ownership of `id.linked.cm` before seeding real
-// data under these IRIs; changing the baseUri afterwards means re-materializing.
+// First-party LINKED package: no `baseUri`, so core's default root applies and
+// IRIs follow the public rule — shapes `https://linked.cm/shape/translation/{ShapeName}`,
+// package `https://linked.cm/pkg/translation` (arch-02 "Public community").
 export const {
   linkedShape,
   linkedUtil,
@@ -14,6 +11,4 @@ export const {
   packageExports,
   packageName,
   getPackageShape,
-} = linkedPackage('@_linked/translation', {
-  baseUri: 'https://id.linked.cm/translation/',
-});
+} = linkedPackage('@_linked/translation');

package/src/react.tsx

@@ -4,24 +4,67 @@ import {
 } from './languages.js';
 import React, {
   createContext,
+  startTransition,
   useCallback,
   useContext,
   useEffect,
   useMemo,
   useState,
+  useSyncExternalStore,
 } from 'react';
 import {
   directionFor,
   type MessageFormat,
+  pseudoExpand,
+  pseudoLocalize,
   translate,
   type TranslationMessages,
 } from './core/messages.js';
 
+/**
+ * Window event that previews a language, text direction or pseudo-locale in
+ * every mounted `TranslationProvider`, without changing the user's language.
+ *
+ * Dispatch it with a {@link TranslationPreviewDetail}:
+ *
+ * ```ts
+ * window.dispatchEvent(
+ *   new CustomEvent(TRANSLATION_PREVIEW_EVENT, {
+ *     detail: { language: 'ar', direction: 'ltr', pseudoLocale: 'expanded' },
+ *   })
+ * );
+ * ```
+ *
+ * Each event replaces the whole preview: a field that is missing or invalid
+ * falls back to its default (no preview language, `'auto'`, `'off'`), so an
+ * empty detail ends the preview. The preview language is never written to
+ * storage, and a preview direction wins over the language's own direction.
+ */
+export const TRANSLATION_PREVIEW_EVENT = 'linked:translation-preview';
+
+export type TranslationPreviewDirection = 'auto' | 'ltr' | 'rtl';
+export type TranslationPreviewPseudoLocale = 'off' | 'accented' | 'expanded';
+
+/** The `detail` of a {@link TRANSLATION_PREVIEW_EVENT}. */
+export interface TranslationPreviewDetail {
+  /** BCP-47 tag to render in instead of the selected language. */
+  language?: string;
+  /** Force a text direction; `'auto'` uses the language's own. */
+  direction?: TranslationPreviewDirection;
+  /**
+   * `'accented'` accents every message; `'expanded'` pads every message by
+   * about a third to show controls that only fit their English copy.
+   */
+  pseudoLocale?: TranslationPreviewPseudoLocale;
+}
+
+const EMPTY_MESSAGES: Record<string, TranslationMessages> = {};
+
 /**
  * React binding for the translation core (Plan 014 P1.5). Kept in a `/react`
  * subpath so non-React consumers use `./core/messages` without pulling React.
  * Message LOADING is caller-injected (`loadMessages`) so this stays transport-
- * agnostic: dev wires it to CN's API, prod to the bundled `{lang}.json` with a
+ * agnostic: dev wires it to the host's API, prod to the bundled `{lang}.json` with a
  * CDN overlay (AD-J/AD-K) — the provider doesn't care which.
  *
  * The hook shape mirrors Tolgee (`useTranslate().t(key, default, params)`,
@@ -40,13 +83,17 @@ export interface TranslationCallOptions {
   format?: MessageFormat;
 }
 
+type TranslateFn = (
+  key: string,
+  defaultValue?: string,
+  params?: Record<string, unknown>,
+  options?: TranslationCallOptions
+) => string;
+
 interface TranslationContextValue {
-  t: (
-    key: string,
-    defaultValue?: string,
-    params?: Record<string, unknown>,
-    options?: TranslationCallOptions
-  ) => string;
+  t: TranslateFn;
+  /** `t` over no catalog: exactly what the server rendered. */
+  tInline: TranslateFn;
   language: string;
   setLanguage: (tag: string) => void;
   languages: TranslationLanguage[];
@@ -97,9 +144,19 @@ export function TranslationProvider({
     }
     return defaultLanguage;
   });
+  const [previewLanguage, setPreviewLanguage] = useState<string | null>(null);
+  const [previewPseudoLocale, setPreviewPseudoLocale] =
+    useState<TranslationPreviewPseudoLocale>('off');
+  const [previewDirection, setPreviewDirection] =
+    useState<TranslationPreviewDirection>('auto');
+  const effectiveLanguage = previewLanguage ?? language;
+  // A preview direction is an editor coordinate and wins; otherwise the
+  // configured language's own direction, then the tag's script default.
   const dir =
-    languages.find((item) => item.tag === language)?.direction ??
-    directionFor(language);
+    previewDirection === 'ltr' || previewDirection === 'rtl'
+      ? previewDirection
+      : (languages.find((item) => item.tag === effectiveLanguage)?.direction ??
+        directionFor(effectiveLanguage));
   useEffect(() => {
     if (!loadLanguages) return;
     let cancelled = false;
@@ -133,10 +190,10 @@ export function TranslationProvider({
   // Load the active language's messages once. English renders from inline
   // defaults until (and if) a payload arrives, so the app is never blank.
   useEffect(() => {
-    if (messagesByLang[language]) return;
+    if (messagesByLang[effectiveLanguage]) return;
     let cancelled = false;
     const chain = languageFallbacks(
-      language,
+      effectiveLanguage,
       defaultLanguage,
       remoteLanguages
     ).reverse();
@@ -144,7 +201,15 @@ export function TranslationProvider({
       .then((maps) => Object.assign({}, ...maps) as TranslationMessages)
       .then((msgs) => {
         if (!cancelled) {
-          setMessagesByLang((prev) => ({ ...prev, [language]: msgs }));
+          // A descendant lazy route may still be hydrating when the catalog
+          // arrives. Overlay messages without replacing its server-rendered
+          // DOM; inline defaults remain usable until the transition commits.
+          startTransition(() => {
+            setMessagesByLang((prev) => ({
+              ...prev,
+              [effectiveLanguage]: msgs,
+            }));
+          });
         }
       })
       .catch(() => {
@@ -154,20 +219,50 @@ export function TranslationProvider({
       cancelled = true;
     };
   }, [
-    language,
+    effectiveLanguage,
     loadMessages,
     messagesByLang,
     defaultLanguage,
     remoteLanguages,
   ]);
 
-  // Reflect the configured language and text direction on <html>.
+  // Preview locale is an ephemeral editor coordinate. It intentionally does
+  // not call setLanguage(), because doing so would persist a test condition as
+  // the app user's real language preference.
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+    const onPreview = (event: Event) => {
+      const detail = (event as CustomEvent<TranslationPreviewDetail | null>)
+        .detail;
+      const nextLanguage: unknown = detail?.language;
+      const nextPseudoLocale: unknown = detail?.pseudoLocale;
+      const nextDirection: unknown = detail?.direction;
+      setPreviewLanguage(
+        typeof nextLanguage === 'string' && nextLanguage ? nextLanguage : null
+      );
+      setPreviewPseudoLocale(
+        nextPseudoLocale === 'accented' || nextPseudoLocale === 'expanded'
+          ? nextPseudoLocale
+          : 'off'
+      );
+      setPreviewDirection(
+        nextDirection === 'ltr' || nextDirection === 'rtl'
+          ? nextDirection
+          : 'auto'
+      );
+    };
+    window.addEventListener(TRANSLATION_PREVIEW_EVENT, onPreview);
+    return () =>
+      window.removeEventListener(TRANSLATION_PREVIEW_EVENT, onPreview);
+  }, []);
+
+  // Reflect the effective language and text direction on <html>.
   useEffect(() => {
     if (typeof document !== 'undefined') {
       document.documentElement.dir = dir;
-      document.documentElement.lang = language;
+      document.documentElement.lang = effectiveLanguage;
     }
-  }, [language, dir]);
+  }, [effectiveLanguage, dir]);
 
   const setLanguage = useCallback(
     (tag: string) => {
@@ -179,27 +274,44 @@ export function TranslationProvider({
     [storageKey]
   );
 
-  const t = useCallback(
-    (
-      key: string,
-      defaultValue?: string,
-      params?: Record<string, unknown>,
-      options?: TranslationCallOptions
-    ) =>
-      translate(
-        messagesByLang[language] ?? {},
-        key,
-        defaultValue,
-        params,
-        options?.format ?? format,
-        language
-      ),
-    [messagesByLang, language, format]
+  const translatorFor = useCallback(
+    (catalogs: Record<string, TranslationMessages>): TranslateFn =>
+      (key, defaultValue, params, options) => {
+        const translated = translate(
+          catalogs[effectiveLanguage] ?? {},
+          key,
+          defaultValue,
+          params,
+          options?.format ?? format,
+          effectiveLanguage
+        );
+        if (previewPseudoLocale === 'accented') {
+          return effectiveLanguage.toLowerCase() === 'en-xa'
+            ? translated
+            : pseudoLocalize(translated);
+        }
+        return previewPseudoLocale === 'expanded'
+          ? pseudoExpand(translated)
+          : translated;
+      },
+    [effectiveLanguage, format, previewPseudoLocale]
+  );
+  const t = useMemo(
+    () => translatorFor(messagesByLang),
+    [translatorFor, messagesByLang]
   );
+  const tInline = useMemo(() => translatorFor(EMPTY_MESSAGES), [translatorFor]);
 
   const value = useMemo<TranslationContextValue>(
-    () => ({ t, language, setLanguage, languages, dir }),
-    [t, language, setLanguage, languages, dir]
+    () => ({
+      t,
+      tInline,
+      language: effectiveLanguage,
+      setLanguage,
+      languages,
+      dir,
+    }),
+    [t, tInline, effectiveLanguage, setLanguage, languages, dir]
   );
 
   return (
@@ -219,9 +331,20 @@ function useTranslationContext(hook: string): TranslationContextValue {
 /** Tolgee-compatible: `const { t } = useTranslate()`. */
 export function useTranslate() {
   const ctx = useTranslationContext('useTranslate');
-  return { t: ctx.t };
+  // The server never has a catalog, and a lazy descendant can hydrate after
+  // the catalog has already reached context. Gating per consumer means every
+  // hydrating render replays the inline defaults, then re-renders with the
+  // catalog once that consumer commits.
+  const hydrated = useSyncExternalStore(
+    subscribeNever,
+    () => true,
+    () => false
+  );
+  return { t: hydrated ? ctx.t : ctx.tInline };
 }
 
+const subscribeNever = () => () => {};
+
 /** Active language + switcher + direction + the available languages. */
 export function useLanguage() {
   const ctx = useTranslationContext('useLanguage');

package/src/records.ts

@@ -171,8 +171,9 @@ export interface TranslationEntryRecord {
   /** Optional semantic organization for translations supplied with LINKED shapes. */
   ofShape?: string;
   ofProperty?: string;
+  ofResource?: string;
   fromPackage?: string;
-  /** This app diverged a shape-owned key locally; shape propagation skips it (AD-N). */
+  /** Explicit app wording for a shape/property/resource/package declaration (AD-N). */
   overridden?: boolean;
   currentVersion?: TranslationKeyVersionRecord;
   versions?: TranslationKeyVersionRecord[];

package/src/release.ts

@@ -2,7 +2,11 @@ import type { TranslationLanguageDefinition } from './languages.js';
 import { runChecks, type CheckFinding } from './checks.js';
 import { compileLanguage } from './compile.js';
 import type { TranslationMessages } from './core/messages.js';
-import { classifyKeyVersion, sha256Hex } from './key-version.js';
+import {
+  classifyKeyVersion,
+  createArgumentSignature,
+  sha256Hex,
+} from './key-version.js';
 import {
   isConfirmedBuildDeclaration,
   type TranslationBuildDeclaration,
@@ -183,7 +187,9 @@ export async function translationContractSetHash(
 
 /**
  * Resolve keys extracted from one immutable build workspace to graph versions.
- * Any missing/orphaned/conflicting/default-drifted key fails before publication.
+ * Missing/orphaned/conflicting/default-drifted keys fail before publication.
+ * Explicit app-owned declaration overrides may change wording, never the
+ * exact workspace's declared format or runtime-argument contract.
  */
 export async function buildSnapshotContractSetHash(
   entries: TranslationEntryRecord[],
@@ -245,7 +251,29 @@ export async function buildSnapshotContractSetHash(
     }
     const extractedContract = [...distinct.values()][0];
     const decision = classifyKeyVersion(current, extractedContract);
-    if (decision.action !== 'unchanged') {
+    const explicitDeclarationOverride =
+      entry.overridden === true &&
+      !!(
+        entry.ofShape ||
+        entry.ofProperty ||
+        entry.ofResource ||
+        entry.fromPackage
+      );
+    // source-changed is reached only AFTER the existing classifier has checked
+    // identical format and argument signature. Do not infer the missing format
+    // of a legacy extraction from the very app override being verified.
+    const compatibleAppWording =
+      explicitDeclarationOverride &&
+      decision.reason === 'source-changed' &&
+      (declarationsByKey.get(entry.key) ?? []).every(
+        (item) =>
+          item.format !== undefined && item.namespace === entry.namespace
+      ) &&
+      entry.sourceText === current.sourceText &&
+      entry.format === current.format &&
+      createArgumentSignature(current.sourceText, current.format) ===
+        current.argumentSignature;
+    if (decision.action !== 'unchanged' && !compatibleAppWording) {
       throw new Error(
         `Build translation source for "${entry.key}" does not match its current key version (${decision.reason}).`
       );

package/src/shape-catalog.ts

@@ -7,7 +7,7 @@ import type { TranslationDiscoverySource } from './discovery.js';
 /**
  * Code-canonical translations shipped beside one reusable LINKED shape.
  * Packages may expose this object from code or serialize the same contract as
- * JSON for Host Agent discovery without executing package code.
+ * JSON for a host's discovery tooling without executing package code.
  */
 export interface ShapeTranslationCatalog {
   schemaVersion: 1;