@_linked/translation 0.2.4 → 0.3.0

package/src/formats/json.ts

@@ -13,7 +13,11 @@ import { canonicalLanguageTag } from '../key-version.js';
 
 const textDecoder = new TextDecoder('utf-8', { fatal: true });
 const textEncoder = new TextEncoder();
-const SIDECAR_PATH = 'create-now.exchange.json';
+const SIDECAR_PATH = 'linked.exchange.json';
+/** Pre-0.3.0 sidecar path and format id — read, never written. */
+const LEGACY_SIDECAR_PATH = 'create-now.exchange.json';
+const SIDECAR_FORMAT = 'linked-i18next-zip';
+const LEGACY_SIDECAR_FORMAT = 'create-now-i18next-zip';
 const ZIP_LOCAL_FILE_SIGNATURE = 0x04034b50;
 const ZIP_EMPTY_SIGNATURE = 0x06054b50;
 const ZIP_SPANNED_SIGNATURE = 0x08074b50;
@@ -55,9 +59,9 @@ export interface TranslationJsonSerializeOptions {
   limits?: Partial<TranslationJsonArchiveLimits>;
 }
 
-interface CreateNowJsonSidecar {
+interface TranslationJsonSidecar {
   schemaVersion: 1;
-  format: 'create-now-i18next-zip';
+  format: typeof SIDECAR_FORMAT | typeof LEGACY_SIDECAR_FORMAT;
   exchange: TranslationExchangeDocument;
   files: Record<string, string>;
 }
@@ -356,21 +360,24 @@ function parseStandalone(
   });
 }
 
-function sidecarFromBytes(input: Uint8Array): CreateNowJsonSidecar {
-  const value = parseJsonObject(input, SIDECAR_PATH) as unknown as Partial<
-    CreateNowJsonSidecar
+function sidecarFromBytes(
+  input: Uint8Array,
+  path: string,
+): TranslationJsonSidecar {
+  const value = parseJsonObject(input, path) as unknown as Partial<
+    TranslationJsonSidecar
   >;
   if (
     value.schemaVersion !== 1 ||
-    value.format !== 'create-now-i18next-zip' ||
+    (value.format !== SIDECAR_FORMAT && value.format !== LEGACY_SIDECAR_FORMAT) ||
     !value.exchange ||
     !value.files ||
     typeof value.files !== 'object' ||
     Array.isArray(value.files)
   ) {
-    throw new Error('Create Now JSON ZIP sidecar is invalid.');
+    throw new Error('Translation JSON ZIP sidecar is invalid.');
   }
-  return value as CreateNowJsonSidecar;
+  return value as TranslationJsonSidecar;
 }
 
 function assertMapsEqual(
@@ -384,12 +391,12 @@ function assertMapsEqual(
     actualKeys.length !== expectedKeys.length ||
     actualKeys.some((key, index) => key !== expectedKeys[index])
   ) {
-    throw new Error(`${label} keys do not match the Create Now sidecar.`);
+    throw new Error(`${label} keys do not match the exchange sidecar.`);
   }
   for (const key of expectedKeys) {
     if (actual[key] !== expected[key]) {
       throw new Error(
-        `${label} value for "${key}" does not match the Create Now sidecar.`,
+        `${label} value for "${key}" does not match the exchange sidecar.`,
       );
     }
   }
@@ -400,11 +407,13 @@ function parseArchive(
   options: TranslationJsonParseOptions,
 ): ParsedTranslationExchangeDocument {
   const files = safeUnzipTranslationZip(input, options.limits);
-  const sidecarBytes = files[SIDECAR_PATH];
+  const sidecarPath =
+    files[SIDECAR_PATH] !== undefined ? SIDECAR_PATH : LEGACY_SIDECAR_PATH;
+  const sidecarBytes = files[sidecarPath];
   if (!sidecarBytes) {
     return parseTolgeeArchive(files, options);
   }
-  const sidecar = sidecarFromBytes(sidecarBytes);
+  const sidecar = sidecarFromBytes(sidecarBytes, sidecarPath);
   const exchange = validateTranslationExchangeDocument(sidecar.exchange);
   const expectedLanguages = [
     exchange.sourceLanguage,
@@ -418,22 +427,22 @@ function parseArchive(
       .sort()
       .some((language, index) => language !== fileLanguages[index])
   ) {
-    throw new Error('Create Now JSON ZIP language manifest is incomplete.');
+    throw new Error('Translation JSON ZIP language manifest is incomplete.');
   }
   const usedPaths = new Set<string>();
   for (const language of expectedLanguages) {
     const path = sidecar.files[language];
     if (typeof path !== 'string') {
-      throw new Error(`Create Now JSON ZIP has no file for ${language}.`);
+      throw new Error(`Translation JSON ZIP has no file for ${language}.`);
     }
     assertSafeArchivePath(path);
     if (usedPaths.has(path)) {
-      throw new Error(`Create Now JSON ZIP reuses language file "${path}".`);
+      throw new Error(`Translation JSON ZIP reuses language file "${path}".`);
     }
     usedPaths.add(path);
     const bytes = files[path];
     if (!bytes) {
-      throw new Error(`Create Now JSON ZIP is missing language file "${path}".`);
+      throw new Error(`Translation JSON ZIP is missing language file "${path}".`);
     }
     const actual = flattenJsonObject(parseJsonObject(bytes, path));
     const expected = languageValues(exchange, language);
@@ -534,9 +543,9 @@ export function serializeI18nextJsonZip(
     languageFiles[language] = path;
     files[path] = serializeLanguage(exchange, language, layout);
   }
-  const sidecar: CreateNowJsonSidecar = {
+  const sidecar: TranslationJsonSidecar = {
     schemaVersion: 1,
-    format: 'create-now-i18next-zip',
+    format: SIDECAR_FORMAT,
     exchange,
     files: languageFiles,
   };

package/src/formats/xliff.ts

@@ -10,7 +10,27 @@ import {
 import type { TranslationState } from '../records.js';
 
 const UTF8 = new TextEncoder();
-const CN_NAMESPACE = 'https://create-now.app/ns/translation-exchange/1';
+/**
+ * Our own metadata namespace, a sibling of the translation vocabulary
+ * (`https://id.linked.cm/translation/vocab#`). Files exported before 0.3.0
+ * used a Create Now URI and a `cn:` prefix; the reader below still accepts
+ * both, so those files keep importing.
+ */
+const EXCHANGE_NAMESPACE = 'https://id.linked.cm/translation/exchange/1';
+const PREFIX = 'lt';
+const LEGACY_PREFIX = 'cn';
+/** `from`/`category` on a `<note>`, in current and pre-0.3.0 spelling. */
+const NOTE_ROLES = {
+  description: ['linked-description', 'create-now-description'],
+  target: ['linked-target', 'create-now-target'],
+} as const;
+
+function isNoteRole(
+  value: string | undefined,
+  role: keyof typeof NOTE_ROLES,
+): boolean {
+  return value !== undefined && (NOTE_ROLES[role] as readonly string[]).includes(value);
+}
 const XLIFF_12_NAMESPACE = 'urn:oasis:names:tc:xliff:document:1.2';
 const XLIFF_20_NAMESPACE = 'urn:oasis:names:tc:xliff:document:2.0';
 const XML_MEDIA_TYPE = 'application/xliff+xml';
@@ -301,7 +321,11 @@ function plainText(node: XmlNode | undefined): string | undefined {
 }
 
 function metadata(node: XmlNode, name: string): string | undefined {
-  return node.attributes[`cn:${name}`] ?? attribute(node, name);
+  return (
+    node.attributes[`${PREFIX}:${name}`] ??
+    node.attributes[`${LEGACY_PREFIX}:${name}`] ??
+    attribute(node, name)
+  );
 }
 
 function recognizedState(value: string | undefined): TranslationState | undefined {
@@ -419,12 +443,12 @@ function parse12(
       if (language) targetLanguages.add(language);
       const notes = children(unit, 'note');
       const description = plainText(
-        notes.find((note) => attribute(note, 'from') === 'create-now-description'),
+        notes.find((note) => isNoteRole(attribute(note, 'from'), 'description')),
       );
       const targetNote = plainText(
         notes.find(
           (note) =>
-            attribute(note, 'from') === 'create-now-target' &&
+            isNoteRole(attribute(note, 'from'), 'target') &&
             (!language || !attribute(note, 'lang') || attribute(note, 'lang') === language),
         ),
       );
@@ -475,13 +499,13 @@ function parse20(
       const notes = notesContainer ? children(notesContainer, 'note') : [];
       const description = plainText(
         notes.find(
-          (note) => attribute(note, 'category') === 'create-now-description',
+          (note) => isNoteRole(attribute(note, 'category'), 'description'),
         ),
       );
       const targetNote = plainText(
         notes.find(
           (note) =>
-            attribute(note, 'category') === 'create-now-target' &&
+            isNoteRole(attribute(note, 'category'), 'target') &&
             (!language || !attribute(note, 'lang') || attribute(note, 'lang') === language),
         ),
       );
@@ -545,14 +569,14 @@ function state20(state: TranslationState | undefined): string {
 
 function metadataAttributes(entry: TranslationExchangeEntry): string {
   return [
-    ['cn:key', entry.key],
-    ['cn:namespace', entry.namespace],
-    ['cn:kind', entry.kind],
-    ['cn:format', entry.format],
-    ['cn:key-version-id', entry.keyVersionId],
-    ['cn:source-hash', entry.sourceHash],
-    ['cn:contract-hash', entry.contractHash],
-    ['cn:argument-signature', entry.argumentSignature],
+    [`${PREFIX}:key`, entry.key],
+    [`${PREFIX}:namespace`, entry.namespace],
+    [`${PREFIX}:kind`, entry.kind],
+    [`${PREFIX}:format`, entry.format],
+    [`${PREFIX}:key-version-id`, entry.keyVersionId],
+    [`${PREFIX}:source-hash`, entry.sourceHash],
+    [`${PREFIX}:contract-hash`, entry.contractHash],
+    [`${PREFIX}:argument-signature`, entry.argumentSignature],
   ]
     .filter((pair): pair is [string, string] => pair[1] !== undefined)
     .map(([name, value]) => ` ${name}="${escapeAttribute(value)}"`)
@@ -561,12 +585,12 @@ function metadataAttributes(entry: TranslationExchangeEntry): string {
 
 function rootMetadata(document: TranslationExchangeDocument): string {
   return [
-    ['cn:schema-version', String(document.schemaVersion)],
-    ['cn:app-id', document.appId],
-    ['cn:branch-id', document.branchId],
-    ['cn:exported-at', document.exportedAt],
-    ['cn:revision-watermark', document.revisionWatermark],
-    ['cn:contract-set-hash', document.contractSetHash],
+    [`${PREFIX}:schema-version`, String(document.schemaVersion)],
+    [`${PREFIX}:app-id`, document.appId],
+    [`${PREFIX}:branch-id`, document.branchId],
+    [`${PREFIX}:exported-at`, document.exportedAt],
+    [`${PREFIX}:revision-watermark`, document.revisionWatermark],
+    [`${PREFIX}:contract-set-hash`, document.contractSetHash],
   ]
     .filter((pair): pair is [string, string] => pair[1] !== undefined)
     .map(([name, value]) => ` ${name}="${escapeAttribute(value)}"`)
@@ -611,25 +635,25 @@ function serialize12(document: TranslationExchangeDocument): string {
           const id = deterministicId(entry, index);
           const notes = [
             entry.description
-              ? `<note from="create-now-description">${escapeText(entry.description)}</note>`
+              ? `<note from="${NOTE_ROLES.description[0]}">${escapeText(entry.description)}</note>`
               : '',
             target?.note
-              ? `<note from="create-now-target" xml:lang="${escapeAttribute(language!)}">${escapeText(target.note)}</note>`
+              ? `<note from="${NOTE_ROLES.target[0]}" xml:lang="${escapeAttribute(language!)}">${escapeText(target.note)}</note>`
               : '',
           ].join('');
           return `<trans-unit id="${escapeAttribute(id)}" resname="${escapeAttribute(entry.key)}"${metadataAttributes(entry)}><source>${validatedMixedContent(entry.sourceText, INLINE_12)}</source>${
             language && target
-              ? `<target xml:lang="${escapeAttribute(language)}" state="${state12(target?.state)}" cn:state="${escapeAttribute(target?.state ?? 'untranslated')}">${validatedMixedContent(target?.text ?? '', INLINE_12)}</target>`
+              ? `<target xml:lang="${escapeAttribute(language)}" state="${state12(target?.state)}" ${PREFIX}:state="${escapeAttribute(target?.state ?? 'untranslated')}">${validatedMixedContent(target?.text ?? '', INLINE_12)}</target>`
               : ''
           }${notes}</trans-unit>`;
         })
         .join('');
-      return `<file id="f${fileIndex + 1}" original="create-now" datatype="plaintext" source-language="${escapeAttribute(document.sourceLanguage)}"${
+      return `<file id="f${fileIndex + 1}" original="linked" datatype="plaintext" source-language="${escapeAttribute(document.sourceLanguage)}"${
         language ? ` target-language="${escapeAttribute(language)}"` : ''
       }><body>${units}</body></file>`;
     })
     .join('');
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<xliff xmlns="${XLIFF_12_NAMESPACE}" xmlns:cn="${CN_NAMESPACE}" version="1.2"${rootMetadata(document)}>${files}</xliff>\n`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<xliff xmlns="${XLIFF_12_NAMESPACE}" xmlns:${PREFIX}="${EXCHANGE_NAMESPACE}" version="1.2"${rootMetadata(document)}>${files}</xliff>\n`;
 }
 
 function serialize20(document: TranslationExchangeDocument): string {
@@ -643,15 +667,15 @@ function serialize20(document: TranslationExchangeDocument): string {
             entry.description || target?.note
               ? `<notes>${
                   entry.description
-                    ? `<note category="create-now-description">${escapeText(entry.description)}</note>`
+                    ? `<note category="${NOTE_ROLES.description[0]}">${escapeText(entry.description)}</note>`
                     : ''
                 }${
                   target?.note
-                    ? `<note category="create-now-target" xml:lang="${escapeAttribute(language!)}">${escapeText(target.note)}</note>`
+                    ? `<note category="${NOTE_ROLES.target[0]}" xml:lang="${escapeAttribute(language!)}">${escapeText(target.note)}</note>`
                     : ''
                 }</notes>`
               : '';
-          return `<unit id="${escapeAttribute(id)}" name="${escapeAttribute(entry.key)}"${metadataAttributes(entry)}>${notes}<segment id="s1" state="${state20(target?.state)}" cn:state="${escapeAttribute(target?.state ?? 'untranslated')}"><source>${validatedMixedContent(entry.sourceText, INLINE_20)}</source>${
+          return `<unit id="${escapeAttribute(id)}" name="${escapeAttribute(entry.key)}"${metadataAttributes(entry)}>${notes}<segment id="s1" state="${state20(target?.state)}" ${PREFIX}:state="${escapeAttribute(target?.state ?? 'untranslated')}"><source>${validatedMixedContent(entry.sourceText, INLINE_20)}</source>${
             language && target
               ? `<target xml:lang="${escapeAttribute(language)}">${validatedMixedContent(target?.text ?? '', INLINE_20)}</target>`
               : ''
@@ -659,7 +683,7 @@ function serialize20(document: TranslationExchangeDocument): string {
         })
         .join('');
       return `<file id="f${fileIndex + 1}"${
-        language ? ` cn:target-language="${escapeAttribute(language)}"` : ''
+        language ? ` ${PREFIX}:target-language="${escapeAttribute(language)}"` : ''
       }>${units}</file>`;
     })
     .join('');
@@ -667,7 +691,7 @@ function serialize20(document: TranslationExchangeDocument): string {
     document.targetLanguages.length === 1
       ? ` trgLang="${escapeAttribute(document.targetLanguages[0])}"`
       : '';
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<xliff xmlns="${XLIFF_20_NAMESPACE}" xmlns:cn="${CN_NAMESPACE}" version="2.0" srcLang="${escapeAttribute(document.sourceLanguage)}"${singleTarget}${rootMetadata(document)}>${files}</xliff>\n`;
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<xliff xmlns="${XLIFF_20_NAMESPACE}" xmlns:${PREFIX}="${EXCHANGE_NAMESPACE}" version="2.0" srcLang="${escapeAttribute(document.sourceLanguage)}"${singleTarget}${rootMetadata(document)}>${files}</xliff>\n`;
 }
 
 function sniffVersion(

package/src/index.ts

@@ -1,7 +1,7 @@
 // Isomorphic barrel (Plan 014 AD-G): side-effect imports register the ontology
 // + shapes into the LINKED tree. Safe on client and server — no backend/Node
 // code here (that lives in ./backend.ts). Ontology FIRST, then shapes.
-import './ontologies/translation.js';
+import './ontologies/translation.register.js';
 import './shapes/TranslationKey.js';
 import './shapes/TranslationKeyVersion.js';
 import './shapes/TranslationRelease.js';

package/src/ontologies/translation.register.ts

@@ -0,0 +1,17 @@
+/**
+ * Registers this ontology.
+ *
+ * Kept out of `translation.ts` because registration needs that module's whole export
+ * namespace, and a module cannot import itself once a bundler is involved: Rollup
+ * treats a static self-reference as a circular import and elides it, so the binding is
+ * undefined at runtime and the consuming app dies at boot with `_this is not
+ * defined`. `tsc` preserves it, which is why the pattern survived for as long as
+ * packages were built with `tsc` alone.
+ *
+ * From a sibling module the same import is ordinary and survives.
+ */
+import * as terms from './translation.js';
+import {loadData, ns} from './translation.js';
+import {linkedOntology} from '../package.js';
+
+linkedOntology(terms, ns, 'translation', loadData, '../data/translation.json');

package/src/ontologies/translation.ts

@@ -1,6 +1,4 @@
 import { createNameSpace } from '@_linked/core/utils/NameSpace';
-import { linkedOntology } from '../package.js';
-import * as _this from './translation.js';
 
 /** Lazy-load the (currently empty) serialized ontology graph. */
 export var loadData = () => {
@@ -231,4 +229,3 @@ export const tr = {
   inventoryObservedAt,
 };
 
-linkedOntology(_this, ns, 'translation', loadData, '../data/translation.json');

package/src/shapes/TranslationProvider.ts

@@ -1426,7 +1426,7 @@ export class TranslationProvider extends ShapeProvider {
 
   /**
    * Authoring gate. Reads `linkedAuth` off the request the LINKED server already
-   * populates — framework-level, so this stays portable (no CN/create-now-js
+   * populates — framework-level, so this stays portable (no Create Now
    * import, AD-G). Anonymous callers can no longer read or write an app's
    * translation content via `/call`. Fine-grained "is translation enabled for
    * this app + is the caller a project member" gating is a Create Now concern and