@_linked/translation 0.2.2

package/src/package.ts

@@ -0,0 +1,19 @@
+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.
+export const {
+  linkedShape,
+  linkedUtil,
+  linkedOntology,
+  registerPackageExport,
+  packageExports,
+  packageName,
+  getPackageShape,
+} = linkedPackage('@_linked/translation', {
+  baseUri: 'https://id.linked.cm/translation/',
+});

package/src/react.tsx

@@ -0,0 +1,250 @@
+import {
+  languageFallbacks,
+  type TranslationLanguageDefinition,
+} from './languages.js';
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
+import {
+  directionFor,
+  type MessageFormat,
+  translate,
+  type TranslationMessages,
+} from './core/messages.js';
+
+/**
+ * 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
+ * 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;
+}
+
+interface TranslationContextValue {
+  t: (
+    key: string,
+    defaultValue?: string,
+    params?: Record<string, unknown>,
+    options?: TranslationCallOptions
+  ) => string;
+  language: string;
+  setLanguage: (tag: string) => void;
+  languages: TranslationLanguage[];
+  dir: 'ltr' | 'rtl';
+}
+
+const 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 dir =
+    languages.find((item) => item.tag === language)?.direction ??
+    directionFor(language);
+  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[language]) return;
+    let cancelled = false;
+    const chain = languageFallbacks(
+      language,
+      defaultLanguage,
+      remoteLanguages
+    ).reverse();
+    Promise.all(chain.map((code) => loadMessages(code).catch(() => ({}))))
+      .then((maps) => Object.assign({}, ...maps) as TranslationMessages)
+      .then((msgs) => {
+        if (!cancelled) {
+          setMessagesByLang((prev) => ({ ...prev, [language]: msgs }));
+        }
+      })
+      .catch(() => {
+        /* offline / missing → keep inline defaults */
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    language,
+    loadMessages,
+    messagesByLang,
+    defaultLanguage,
+    remoteLanguages,
+  ]);
+
+  // Reflect the configured language and text direction on <html>.
+  useEffect(() => {
+    if (typeof document !== 'undefined') {
+      document.documentElement.dir = dir;
+      document.documentElement.lang = language;
+    }
+  }, [language, dir]);
+
+  const setLanguage = useCallback(
+    (tag: string) => {
+      setLanguageState(tag);
+      if (typeof window !== 'undefined') {
+        window.localStorage?.setItem(storageKey, tag);
+      }
+    },
+    [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 value = useMemo<TranslationContextValue>(
+    () => ({ t, language, setLanguage, languages, dir }),
+    [t, language, 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');
+  return { t: ctx.t };
+}
+
+/** 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 })}</>;
+}

package/src/records.ts

@@ -0,0 +1,180 @@
+/** Review lifecycle shared by the portable runtime and authoring clients. */
+export type TranslationState =
+  | 'untranslated'
+  | 'machine'
+  | 'reviewed'
+  | 'stale';
+
+/** Plain RPC-safe value for one language. Never contains a live Shape. */
+export interface TranslationUnitRecord {
+  language: string;
+  text: string;
+  state: TranslationState;
+  /** Machine-provider provenance for the current value (`tm` for memory). */
+  origin?: string;
+  updatedAt?: string;
+  keyVersionId?: string;
+}
+
+/** Plain immutable source/argument-contract record for Studio and RPC. */
+export interface TranslationKeyVersionRecord {
+  id: string;
+  versionId: string;
+  sourceLanguage: string;
+  sourceText: string;
+  format: 'simple' | 'icu';
+  argumentSignature: string;
+  contractHash: string;
+  sourceHash: string;
+  supersedes?: string;
+  createdAt?: string;
+  createdBy?: string;
+}
+
+export type TranslationReleaseChannel = 'preview' | 'production';
+export type TranslationReleaseStatus =
+  | 'draft'
+  | 'published'
+  | 'superseded'
+  | 'retired';
+
+/** Plain graph metadata for a schema-v2 translation release. */
+export interface TranslationReleaseRecord {
+  id: string;
+  releaseId: string;
+  appId: string;
+  branchId: string;
+  buildId?: string;
+  channel: TranslationReleaseChannel;
+  status: TranslationReleaseStatus;
+  contractSetHash: string;
+  manifestHash: string;
+  hotfixSequence: number;
+  qualitySummary?: string;
+  createdAt: string;
+  publishedAt?: string;
+  supportedUntil?: string;
+  supersedes?: string;
+}
+
+/** Lifecycle of one authored value (Plan 017 AD-P). */
+export type TranslationRevisionStatus =
+  | 'applied' // a direct edit, recorded as history
+  | 'proposed' // awaiting a reviewer (human author)
+  | 'suggested' // awaiting a reviewer (machine author)
+  | 'accepted'
+  | 'rejected'
+  | 'superseded';
+
+/** Plain RPC-safe view of one revision (history entry / pending value). */
+export interface TranslationRevisionRecord {
+  id: string;
+  key: string;
+  language: string;
+  text: string;
+  status: TranslationRevisionStatus;
+  author?: string;
+  authorKind: 'human' | 'machine';
+  mtProvider?: string;
+  basedOnText?: string;
+  note?: string;
+  createdAt?: string;
+  decidedAt?: string;
+  decidedBy?: string;
+  keyVersionId?: string;
+  /** Current unit diverged after this proposal was authored. */
+  conflicted?: boolean;
+  currentText?: string;
+}
+
+export interface TranslationProposalDecision {
+  revision: TranslationRevisionRecord;
+  unit?: TranslationUnitRecord;
+}
+
+export type TranslationMemoryMatchKind = 'exact' | 'carry-forward';
+
+/**
+ * One reviewed unit that can seed the current key version. Exact source
+ * matches may pretranslate as machine/TM; changed source text is an explicit
+ * same-key carry-forward review.
+ */
+export interface TranslationMemoryMatchRecord {
+  unitId: string;
+  key: string;
+  language: string;
+  text: string;
+  keyVersionId: string;
+  sourceText: string;
+  sourceHash: string;
+  contractHash: string;
+  kind: TranslationMemoryMatchKind;
+  updatedAt?: string;
+}
+
+/** Searchable reviewed unit exposed by the explicit Translation Memory browser. */
+export interface TranslationMemoryRecord {
+  unitId: string;
+  key: string;
+  language: string;
+  text: string;
+  keyVersionId: string;
+  sourceText: string;
+  sourceHash: string;
+  contractHash: string;
+  updatedAt?: string;
+}
+
+export interface TranslationMemoryPretranslateCandidate {
+  key: string;
+  language: string;
+  unitId: string;
+  sourceKey: string;
+  text: string;
+}
+
+export interface TranslationMemoryPretranslateReport {
+  language: string;
+  eligible: number;
+  translated: number;
+  candidates: TranslationMemoryPretranslateCandidate[];
+}
+
+/** Termbase entry behavior (Plan 017 B2-1). */
+export type GlossaryTermType = 'prefer' | 'require' | 'keep' | 'forbid';
+
+/** Plain RPC-safe termbase entry (steers MT + checks; Plan 014 AD-L / 017 B2). */
+export interface GlossaryTermRecord {
+  id: string;
+  term: string;
+  /** prefer = translate as `translation`; keep = do-not-translate; forbid = never use. */
+  termType: GlossaryTermType;
+  /** Preferred translation (prefer entries). */
+  translation?: string;
+  /** Replacement wording (forbid entries — alternative-spelling policing). */
+  useInstead?: string;
+  /** Target language this applies to; empty = all languages. */
+  language?: string;
+  /** Exact-casing match (proper nouns / all-caps styling). */
+  caseSensitive?: boolean;
+  description?: string;
+}
+
+/** Plain RPC-safe editor/runtime view of a key and its language values. */
+export interface TranslationEntryRecord {
+  key: string;
+  namespace: string;
+  sourceText: string;
+  description?: string;
+  kind: 'ui' | 'content';
+  format: 'simple' | 'icu';
+  /** Optional semantic organization for translations supplied with LINKED shapes. */
+  ofShape?: string;
+  ofProperty?: string;
+  fromPackage?: string;
+  /** This app diverged a shape-owned key locally; shape propagation skips it (AD-N). */
+  overridden?: boolean;
+  currentVersion?: TranslationKeyVersionRecord;
+  versions?: TranslationKeyVersionRecord[];
+  units: Record<string, TranslationUnitRecord>;
+}