@_linked/translation 0.9.4 → 0.10.0

package/src/ontologies/translation.ts

@@ -1,239 +0,0 @@
-import { createNameSpace } from '@_linked/core/utils/NameSpace';
-import { loadOntologyFiles } from '@_linked/core/ontology/loadOntologyFiles';
-
-/** The package's ontology data, relative to this module (Turtle, copied into `lib/` by the build). */
-export const dataFiles = ['../data/translation.ttl'];
-
-/** Reads the package's ontology data (server only). */
-export const loadData = () => loadOntologyFiles(import.meta.url, dataFiles);
-
-/**
- * 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
- * (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#`.
- */
-export var ns = createNameSpace('https://linked.cm/ont/translation/');
-export var _self = ns('');
-
-// ── Classes ─────────────────────────────────────────────────────────────
-export var TranslationKey = ns('TranslationKey');
-export var TranslationKeyVersion = ns('TranslationKeyVersion');
-export var TranslationRelease = ns('TranslationRelease');
-export var TranslationUnit = ns('TranslationUnit');
-export var TranslationRevision = ns('TranslationRevision');
-export var GlossaryTerm = ns('GlossaryTerm');
-export var TranslationInventoryOrigin = ns('TranslationInventoryOrigin');
-
-// Open language resources; BCP-47 is a string identifier, not an enum.
-export var TranslationLanguage = ns('TranslationLanguage');
-export var languageIdentifier = ns('languageIdentifier');
-export var languageCode = ns('languageCode');
-export var nativeName = ns('nativeName');
-export var englishName = ns('englishName');
-export var textDirection = ns('textDirection');
-export var parentLanguage = ns('parentLanguage');
-export var fallbackLanguage = ns('fallbackLanguage');
-export var languageEnabled = ns('languageEnabled');
-export var languageSupported = ns('languageSupported');
-
-// ── TranslationKey properties ───────────────────────────────────────────
-export var namespace = ns('namespace');
-export var key = ns('key');
-export var sourceText = ns('sourceText'); // canonical English (Plan 014 AD-J/R7)
-export var description = ns('description');
-export var kind = ns('kind'); // 'ui' | 'content' (AD-I)
-export var ofApplication = ns('ofApplication'); // owning app IRI (AD-H/R2)
-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)
-export var format = ns('format'); // 'simple' | 'icu' (AD-J/R8)
-export var currentVersion = ns('currentVersion'); // → TranslationKeyVersion
-
-// ── TranslationKeyVersion properties (Plan 018) ────────────────────────
-export var versionId = ns('versionId');
-export var sourceLanguage = ns('sourceLanguage');
-export var argumentSignature = ns('argumentSignature');
-export var contractHash = ns('contractHash');
-export var sourceHash = ns('sourceHash');
-export var supersedes = ns('supersedes');
-export var createdBy = ns('createdBy');
-
-// ── TranslationRelease properties (Plan 018) ───────────────────────────
-export var branch = ns('branch');
-export var releaseId = ns('releaseId');
-export var buildId = ns('buildId');
-export var channel = ns('channel');
-export var contractSetHash = ns('contractSetHash');
-export var manifestHash = ns('manifestHash');
-export var hotfixSequence = ns('hotfixSequence');
-export var publishedAt = ns('publishedAt');
-export var supportedUntil = ns('supportedUntil');
-export var qualitySummary = ns('qualitySummary');
-
-// ── 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)
-export var autoPublish = ns('autoPublish'); // boolean — overridable auto-publish-on-edit toggle (P2, default off)
-export var reviewedOnlyLanguage = ns('reviewedOnlyLanguage'); // BCP-47 tags published reviewed-only; absence ⇒ machine-ok (AD-K/R9, P2)
-export var mtDefault = ns('mtDefault'); // default MT provider key (AD-L, unused until P4)
-export var mtFormality = ns('mtFormality'); // multi-value: "formal" (app default) or "de:informal" (per-language) — Plan 017 §7.4b
-export var mtStyleNote = ns('mtStyleNote'); // free-text tone guidance fed to LLM MT providers (Plan 017 §7.4b)
-
-// ── TranslationUnit properties ──────────────────────────────────────────
-export var ofKey = ns('ofKey'); // → TranslationKey
-export var ofKeyVersion = ns('ofKeyVersion'); // → TranslationKeyVersion
-export var language = ns('language'); // BCP-47 tag
-export var text = ns('text');
-export var state = ns('state'); // untranslated | machine | reviewed | stale
-export var updatedAt = ns('updatedAt');
-export var updatedBy = ns('updatedBy');
-export var origin = ns('origin'); // current-value provenance, e.g. `tm`
-
-// ── TranslationRevision properties (Plan 017 AD-P) ─────────────────────
-// One append-only node per authored value: history (`applied`), translator
-// proposals (`proposed`), and MT suggestions (`suggested`) share the shape.
-export var status = ns('status'); // applied | proposed | suggested | accepted | rejected | superseded
-export var author = ns('author'); // WebID or MT provider IRI
-export var authorKind = ns('authorKind'); // 'human' | 'machine'
-export var mtProvider = ns('mtProvider'); // provider key when authorKind=machine
-export var basedOnText = ns('basedOnText'); // unit text at authoring time (conflict detection)
-export var note = ns('note'); // translator/reviewer comment
-export var createdAt = ns('createdAt');
-export var decidedAt = ns('decidedAt'); // when a proposal/suggestion was accepted/rejected
-export var decidedBy = ns('decidedBy'); // WebID of the reviewer
-
-// ── GlossaryTerm properties ─────────────────────────────────────────────
-export var term = ns('term');
-export var glossaryTranslation = ns('glossaryTranslation');
-export var glossaryLanguage = ns('glossaryLanguage');
-export var termType = ns('termType'); // prefer | require | keep | forbid (Plan 017 B2-1 termbase)
-export var useInstead = ns('useInstead'); // replacement for a forbidden term/spelling
-export var caseSensitive = ns('caseSensitive'); // boolean — exact-casing matching (proper nouns)
-
-// ── Branch translation inventory metadata (Plan 017 Phase 8b) ─────────
-// These records are materialized into the active branch metadata dataset,
-// never app data. Confirmed TranslationKey/TranslationUnit records retain
-// their existing app-data placement.
-export var inventoryBranch = ns('inventoryBranch');
-export var inventoryIdentity = ns('inventoryIdentity');
-export var inventoryStatus = ns('inventoryStatus');
-export var inventorySource = ns('inventorySource');
-export var inventorySourceId = ns('inventorySourceId');
-export var inventoryAuthoritative = ns('inventoryAuthoritative');
-export var inventoryFile = ns('inventoryFile');
-export var inventoryLine = ns('inventoryLine');
-export var inventoryOwner = ns('inventoryOwner');
-export var inventoryShape = ns('inventoryShape');
-export var inventoryProperty = ns('inventoryProperty');
-export var inventoryNode = ns('inventoryNode');
-export var inventoryTargetClass = ns('inventoryTargetClass');
-export var inventoryObservedAt = ns('inventoryObservedAt');
-
-/** Grouped export for prefix/name access. */
-export const tr = {
-  TranslationLanguage,
-  languageIdentifier,
-  languageCode,
-  nativeName,
-  englishName,
-  textDirection,
-  parentLanguage,
-  fallbackLanguage,
-  languageEnabled,
-  languageSupported,
-  TranslationKey,
-  TranslationKeyVersion,
-  TranslationRelease,
-  TranslationUnit,
-  TranslationRevision,
-  GlossaryTerm,
-  TranslationInventoryOrigin,
-  namespace,
-  key,
-  sourceText,
-  description,
-  kind,
-  ofApplication,
-  ofNode,
-  ofField,
-  ofShape,
-  ofProperty,
-  ofResource,
-  fromPackage,
-  overridden,
-  shapeSource,
-  format,
-  currentVersion,
-  versionId,
-  sourceLanguage,
-  argumentSignature,
-  contractHash,
-  sourceHash,
-  supersedes,
-  createdBy,
-  branch,
-  releaseId,
-  buildId,
-  channel,
-  contractSetHash,
-  manifestHash,
-  hotfixSequence,
-  publishedAt,
-  supportedUntil,
-  qualitySummary,
-  languages,
-  defaultLanguage,
-  cdnTarget,
-  autoPublish,
-  reviewedOnlyLanguage,
-  mtDefault,
-  mtFormality,
-  mtStyleNote,
-  ofKey,
-  ofKeyVersion,
-  language,
-  text,
-  state,
-  updatedAt,
-  updatedBy,
-  origin,
-  status,
-  author,
-  authorKind,
-  mtProvider,
-  basedOnText,
-  note,
-  createdAt,
-  decidedAt,
-  decidedBy,
-  term,
-  glossaryTranslation,
-  glossaryLanguage,
-  termType,
-  useInstead,
-  caseSensitive,
-  inventoryBranch,
-  inventoryIdentity,
-  inventoryStatus,
-  inventorySource,
-  inventorySourceId,
-  inventoryAuthoritative,
-  inventoryFile,
-  inventoryLine,
-  inventoryOwner,
-  inventoryShape,
-  inventoryProperty,
-  inventoryNode,
-  inventoryTargetClass,
-  inventoryObservedAt,
-};
-

package/src/package.ts

@@ -1,14 +0,0 @@
-import { linkedPackage } from '@_linked/core/utils/Package';
-
-// 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,
-  linkedOntology,
-  registerPackageExport,
-  packageExports,
-  packageName,
-  getPackageShape,
-} = linkedPackage('@_linked/translation');

package/src/react.tsx

@@ -1,378 +0,0 @@
-import { sharedState } from '@_linked/core/utils/sharedState';
-import {
-  languageFallbacks,
-  type TranslationLanguageDefinition,
-} 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 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)`,
- * `useLanguage()`), so swapping serve's provider touches only its i18n file.
- */
-
-export interface TranslationLanguage {
-  tag: string; // BCP-47
-  label: string;
-  direction?: 'ltr' | 'rtl';
-  fallback?: string;
-}
-
-export interface TranslationCallOptions {
-  /** Explicit syntax for an inline default before per-key catalog metadata loads. */
-  format?: MessageFormat;
-}
-
-type TranslateFn = (
-  key: string,
-  defaultValue?: string,
-  params?: Record<string, unknown>,
-  options?: TranslationCallOptions
-) => string;
-
-interface TranslationContextValue {
-  t: TranslateFn;
-  /** `t` over no catalog: exactly what the server rendered. */
-  tInline: TranslateFn;
-  language: string;
-  setLanguage: (tag: string) => void;
-  languages: TranslationLanguage[];
-  dir: 'ltr' | 'rtl';
-}
-
-// The context object is kept on globalThis: a context created per copy of this module would
-// leave a consumer in one copy blind to a provider from the other (it gets the null default).
-const { TranslationContext } = sharedState('@_linked/translation', 'react.contexts', () => ({
-  TranslationContext: createContext<TranslationContextValue | null>(null),
-}));
-
-export interface TranslationProviderProps {
-  children: React.ReactNode;
-  languages: TranslationLanguage[];
-  /** Optional live catalog metadata, refreshed independently of an app build. */
-  loadLanguages?: () => Promise<TranslationLanguageDefinition[]>;
-  defaultLanguage?: string;
-  /** Global message format. 'simple' = FormatSimple (Tolgee-compatible default). */
-  format?: MessageFormat;
-  /** Caller-injected loader: dev→API, prod→bundled file then CDN overlay. */
-  loadMessages: (language: string) => Promise<TranslationMessages>;
-  /** localStorage key persisting the selected language. */
-  storageKey?: string;
-}
-
-export function TranslationProvider({
-  children,
-  languages: initialLanguages,
-  loadLanguages,
-  defaultLanguage = 'en',
-  format = 'simple',
-  loadMessages,
-  storageKey = 'linked.lang',
-}: TranslationProviderProps) {
-  const [remoteLanguages, setRemoteLanguages] =
-    useState<TranslationLanguageDefinition[]>();
-  const languages = remoteLanguages
-    ? remoteLanguages
-        .filter((item) => item.enabled && item.supported)
-        .map((item) => ({
-          tag: item.code,
-          label: item.nativeName,
-          direction: item.direction,
-          fallback: item.fallback,
-        }))
-    : initialLanguages;
-  const [language, setLanguageState] = useState<string>(() => {
-    if (typeof window !== 'undefined') {
-      const stored = window.localStorage?.getItem(storageKey);
-      if (stored && languages.some((l) => l.tag === stored)) return stored;
-    }
-    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 =
-    previewDirection === 'ltr' || previewDirection === 'rtl'
-      ? previewDirection
-      : (languages.find((item) => item.tag === effectiveLanguage)?.direction ??
-        directionFor(effectiveLanguage));
-  useEffect(() => {
-    if (!loadLanguages) return;
-    let cancelled = false;
-    loadLanguages()
-      .then((items) => {
-        if (!cancelled) {
-          setRemoteLanguages(items);
-          setMessagesByLang({});
-          const stored =
-            typeof window !== 'undefined'
-              ? window.localStorage?.getItem(storageKey)
-              : null;
-          if (
-            stored &&
-            items.some(
-              (item) => item.code === stored && item.enabled && item.supported
-            )
-          )
-            setLanguageState(stored);
-        }
-      })
-      .catch(() => {});
-    return () => {
-      cancelled = true;
-    };
-  }, [loadLanguages, storageKey]);
-  const [messagesByLang, setMessagesByLang] = useState<
-    Record<string, TranslationMessages>
-  >({});
-
-  // 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[effectiveLanguage]) return;
-    let cancelled = false;
-    const chain = languageFallbacks(
-      effectiveLanguage,
-      defaultLanguage,
-      remoteLanguages
-    ).reverse();
-    Promise.all(chain.map((code) => loadMessages(code).catch(() => ({}))))
-      .then((maps) => Object.assign({}, ...maps) as TranslationMessages)
-      .then((msgs) => {
-        if (!cancelled) {
-          // 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(() => {
-        /* offline / missing → keep inline defaults */
-      });
-    return () => {
-      cancelled = true;
-    };
-  }, [
-    effectiveLanguage,
-    loadMessages,
-    messagesByLang,
-    defaultLanguage,
-    remoteLanguages,
-  ]);
-
-  // 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 = effectiveLanguage;
-    }
-  }, [effectiveLanguage, dir]);
-
-  const setLanguage = useCallback(
-    (tag: string) => {
-      setLanguageState(tag);
-      if (typeof window !== 'undefined') {
-        window.localStorage?.setItem(storageKey, tag);
-      }
-    },
-    [storageKey]
-  );
-
-  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,
-      tInline,
-      language: effectiveLanguage,
-      setLanguage,
-      languages,
-      dir,
-    }),
-    [t, tInline, effectiveLanguage, setLanguage, languages, dir]
-  );
-
-  return (
-    <TranslationContext.Provider value={value}>
-      {children}
-    </TranslationContext.Provider>
-  );
-}
-
-function useTranslationContext(hook: string): TranslationContextValue {
-  const ctx = useContext(TranslationContext);
-  if (!ctx)
-    throw new Error(`${hook} must be used within a <TranslationProvider>`);
-  return ctx;
-}
-
-/** Tolgee-compatible: `const { t } = useTranslate()`. */
-export function useTranslate() {
-  const ctx = useTranslationContext('useTranslate');
-  // 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');
-  return {
-    language: ctx.language,
-    setLanguage: ctx.setLanguage,
-    languages: ctx.languages,
-    dir: ctx.dir,
-  };
-}
-
-/** JSX convenience (Tolgee `<T keyName=… />`). */
-export function T({
-  keyName,
-  defaultValue,
-  params,
-  format,
-}: {
-  keyName: string;
-  defaultValue?: string;
-  params?: Record<string, unknown>;
-  format?: MessageFormat;
-}) {
-  const { t } = useTranslate();
-  return <>{t(keyName, defaultValue, params, { format })}</>;
-}