@lp-labs/translation-workflow 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,71 @@
-# Temporary Holding Version
+# @lp-labs/translation-workflow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bounded translation catalog comparison with sorted key changes, simple named-placeholder
+compatibility checks, and validated review metadata.
+
+```js
+import { diffTranslationCatalogs, createTranslationReview } from '@lp-labs/translation-workflow';
+
+const diff = diffTranslationCatalogs(
+  { greeting: 'Hello, {name}!' },
+  { greeting: 'Bonjour, {name}!', newer: 'Bienvenue' },
+);
+console.log(diff.compatible, diff.added, diff.changed);
+console.log(
+  createTranslationReview({
+    locale: 'fr-FR',
+    key: 'greeting',
+    reviewer: 'editor-1',
+    status: 'approved',
+    reviewedAt: '2026-11-05T08:00:00Z',
+  }),
+);
+```
+
+## Install
+
+```sh
+npm install @lp-labs/translation-workflow
+```
+
+## API
+
+- `diffTranslationCatalogs(source, target): TranslationCatalogDiff` compares own string entries in
+  two `TranslationCatalog` objects. `added` are target-only keys; `missing` are source-only keys;
+  `changed` are shared keys with different text; `placeholderMismatches` are shared keys whose
+  `{name}` placeholder multisets differ. The frozen result's `compatible` flag is false only when
+  at least one shared key has a placeholder mismatch.
+- `TranslationCatalog` is a string-keyed catalog type.
+- `TranslationCatalogDiff` exposes readonly sorted arrays `added`, `missing`, `changed`, and
+  `placeholderMismatches`, plus `compatible`.
+- `createTranslationReview(input: TranslationReviewInput): TranslationReview` validates and freezes
+  a review record. Required fields are `locale`, `key`, `reviewer`, `status`, and `reviewedAt`;
+  statuses are `draft`, `reviewed`, `approved`, or `rejected`. Optional `note` is limited to 2000
+  characters. Timestamps must be ISO UTC strings ending in `Z`.
+- `TranslationReviewInput` and `TranslationReview` describe the review input and frozen output.
+
+Catalogs must be plain own-property records with at most 10,000 entries, keys from 1–256
+characters, and string values of at most 10,000 characters. Reviews use plain own enumerable data
+properties only; locale, key, and reviewer each have a 1–256 character limit. Unknown fields,
+accessors, symbols, and inherited records are rejected. Invalid values throw `TypeError` or
+`RangeError`.
+
+## Customization and limits
+
+Use the diff arrays to gate a human review or to display a bounded change list; store returned review
+records in your own persistence layer. Placeholder recognition is intentionally limited to simple
+`{name}` identifiers (letters followed by letters, digits, `_`, `.`, or `-`). This utility does not
+extract strings from source code, parse ICU MessageFormat, validate plural/select branches, or
+replace a translation platform. Catalog ordering is deterministic and independent of insertion
+order.
+
+Package scripts: `npm run build`, `npm run typecheck`, `npm test`, `npm run format`, and
+`npm run format:check`. Requires Node.js 18 or newer. There are no runtime or peer dependencies.
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,28 @@
+export interface TranslationCatalog {
+    readonly [key: string]: string;
+}
+export interface TranslationCatalogDiff {
+    readonly added: readonly string[];
+    readonly missing: readonly string[];
+    readonly changed: readonly string[];
+    readonly placeholderMismatches: readonly string[];
+    readonly compatible: boolean;
+}
+export interface TranslationReviewInput {
+    locale: string;
+    key: string;
+    reviewer: string;
+    status: 'draft' | 'reviewed' | 'approved' | 'rejected';
+    reviewedAt: string;
+    note?: string;
+}
+export interface TranslationReview {
+    readonly locale: string;
+    readonly key: string;
+    readonly reviewer: string;
+    readonly status: 'draft' | 'reviewed' | 'approved' | 'rejected';
+    readonly reviewedAt: string;
+    readonly note?: string;
+}
+export declare function diffTranslationCatalogs(source: TranslationCatalog, target: TranslationCatalog): TranslationCatalogDiff;
+export declare function createTranslationReview(input: TranslationReviewInput): TranslationReview;

package/dist/cjs/index.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffTranslationCatalogs = diffTranslationCatalogs;
+exports.createTranslationReview = createTranslationReview;
+function catalogEntries(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        throw new TypeError('Catalogs must be plain string-keyed objects.');
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 10_000)
+        throw new RangeError('Catalogs are limited to 10000 entries.');
+    const entries = new Map();
+    for (const key of keys) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(value, key) : undefined;
+        if (typeof key !== 'string' ||
+            !descriptor?.enumerable ||
+            !('value' in descriptor) ||
+            typeof descriptor.value !== 'string') {
+            throw new TypeError('Catalog entries must be enumerable string data properties.');
+        }
+        if (!key || key.length > 256 || descriptor.value.length > 10_000) {
+            throw new RangeError('Catalog keys are limited to 1..256 characters and values to 10000.');
+        }
+        entries.set(key, descriptor.value);
+    }
+    return entries;
+}
+function placeholders(text) {
+    return [...text.matchAll(/\{([A-Za-z][A-Za-z0-9_.-]{0,127})\}/g)]
+        .map((match) => match[1])
+        .sort();
+}
+function sameStrings(first, second) {
+    return first.length === second.length && first.every((value, index) => value === second[index]);
+}
+function diffTranslationCatalogs(source, target) {
+    const sourceEntries = catalogEntries(source);
+    const targetEntries = catalogEntries(target);
+    const added = [...targetEntries.keys()].filter((key) => !sourceEntries.has(key)).sort();
+    const missing = [...sourceEntries.keys()].filter((key) => !targetEntries.has(key)).sort();
+    const shared = [...sourceEntries.keys()].filter((key) => targetEntries.has(key)).sort();
+    const changed = shared.filter((key) => sourceEntries.get(key) !== targetEntries.get(key));
+    const placeholderMismatches = shared.filter((key) => !sameStrings(placeholders(sourceEntries.get(key)), placeholders(targetEntries.get(key))));
+    return Object.freeze({
+        added: Object.freeze(added),
+        missing: Object.freeze(missing),
+        changed: Object.freeze(changed),
+        placeholderMismatches: Object.freeze(placeholderMismatches),
+        compatible: placeholderMismatches.length === 0,
+    });
+}
+function createTranslationReview(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        (Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null)) {
+        throw new TypeError('Review metadata must be a plain object.');
+    }
+    const allowed = ['locale', 'key', 'reviewer', 'status', 'reviewedAt', 'note'];
+    const values = {};
+    for (const property of Reflect.ownKeys(input)) {
+        const descriptor = typeof property === 'string' ? Object.getOwnPropertyDescriptor(input, property) : undefined;
+        if (typeof property !== 'string' ||
+            !allowed.includes(property) ||
+            !descriptor?.enumerable ||
+            !('value' in descriptor)) {
+            throw new TypeError('Review metadata contains an unsupported or non-data property.');
+        }
+        values[property] = descriptor.value;
+    }
+    for (const key of ['locale', 'key', 'reviewer', 'status', 'reviewedAt']) {
+        if (!Object.hasOwn(values, key))
+            throw new TypeError(`Review field "${key}" is required.`);
+    }
+    for (const key of ['locale', 'key', 'reviewer']) {
+        const value = values[key];
+        if (typeof value !== 'string' || value.length < 1 || value.length > 256) {
+            throw new RangeError(`${key} must contain 1..256 characters.`);
+        }
+    }
+    if (!['draft', 'reviewed', 'approved', 'rejected'].includes(values.status)) {
+        throw new TypeError('status must be draft, reviewed, approved, or rejected.');
+    }
+    const timestamp = typeof values.reviewedAt === 'string' &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(values.reviewedAt)
+        ? Date.parse(values.reviewedAt)
+        : Number.NaN;
+    if (!Number.isFinite(timestamp) ||
+        new Date(timestamp).toISOString().slice(0, 19) !== values.reviewedAt.slice(0, 19)) {
+        throw new TypeError('reviewedAt must be an ISO timestamp ending in Z.');
+    }
+    if (values.note !== undefined && (typeof values.note !== 'string' || values.note.length > 2000)) {
+        throw new RangeError('note must be a string of at most 2000 characters.');
+    }
+    return Object.freeze({
+        locale: values.locale,
+        key: values.key,
+        reviewer: values.reviewer,
+        status: values.status,
+        reviewedAt: values.reviewedAt,
+        ...(values.note === undefined ? {} : { note: values.note }),
+    });
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,28 @@
+export interface TranslationCatalog {
+    readonly [key: string]: string;
+}
+export interface TranslationCatalogDiff {
+    readonly added: readonly string[];
+    readonly missing: readonly string[];
+    readonly changed: readonly string[];
+    readonly placeholderMismatches: readonly string[];
+    readonly compatible: boolean;
+}
+export interface TranslationReviewInput {
+    locale: string;
+    key: string;
+    reviewer: string;
+    status: 'draft' | 'reviewed' | 'approved' | 'rejected';
+    reviewedAt: string;
+    note?: string;
+}
+export interface TranslationReview {
+    readonly locale: string;
+    readonly key: string;
+    readonly reviewer: string;
+    readonly status: 'draft' | 'reviewed' | 'approved' | 'rejected';
+    readonly reviewedAt: string;
+    readonly note?: string;
+}
+export declare function diffTranslationCatalogs(source: TranslationCatalog, target: TranslationCatalog): TranslationCatalogDiff;
+export declare function createTranslationReview(input: TranslationReviewInput): TranslationReview;

package/dist/esm/index.js

@@ -0,0 +1,102 @@
+function catalogEntries(value) {
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) {
+        throw new TypeError('Catalogs must be plain string-keyed objects.');
+    }
+    const keys = Reflect.ownKeys(value);
+    if (keys.length > 10_000)
+        throw new RangeError('Catalogs are limited to 10000 entries.');
+    const entries = new Map();
+    for (const key of keys) {
+        const descriptor = typeof key === 'string' ? Object.getOwnPropertyDescriptor(value, key) : undefined;
+        if (typeof key !== 'string' ||
+            !descriptor?.enumerable ||
+            !('value' in descriptor) ||
+            typeof descriptor.value !== 'string') {
+            throw new TypeError('Catalog entries must be enumerable string data properties.');
+        }
+        if (!key || key.length > 256 || descriptor.value.length > 10_000) {
+            throw new RangeError('Catalog keys are limited to 1..256 characters and values to 10000.');
+        }
+        entries.set(key, descriptor.value);
+    }
+    return entries;
+}
+function placeholders(text) {
+    return [...text.matchAll(/\{([A-Za-z][A-Za-z0-9_.-]{0,127})\}/g)]
+        .map((match) => match[1])
+        .sort();
+}
+function sameStrings(first, second) {
+    return first.length === second.length && first.every((value, index) => value === second[index]);
+}
+export function diffTranslationCatalogs(source, target) {
+    const sourceEntries = catalogEntries(source);
+    const targetEntries = catalogEntries(target);
+    const added = [...targetEntries.keys()].filter((key) => !sourceEntries.has(key)).sort();
+    const missing = [...sourceEntries.keys()].filter((key) => !targetEntries.has(key)).sort();
+    const shared = [...sourceEntries.keys()].filter((key) => targetEntries.has(key)).sort();
+    const changed = shared.filter((key) => sourceEntries.get(key) !== targetEntries.get(key));
+    const placeholderMismatches = shared.filter((key) => !sameStrings(placeholders(sourceEntries.get(key)), placeholders(targetEntries.get(key))));
+    return Object.freeze({
+        added: Object.freeze(added),
+        missing: Object.freeze(missing),
+        changed: Object.freeze(changed),
+        placeholderMismatches: Object.freeze(placeholderMismatches),
+        compatible: placeholderMismatches.length === 0,
+    });
+}
+export function createTranslationReview(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        (Object.getPrototypeOf(input) !== Object.prototype && Object.getPrototypeOf(input) !== null)) {
+        throw new TypeError('Review metadata must be a plain object.');
+    }
+    const allowed = ['locale', 'key', 'reviewer', 'status', 'reviewedAt', 'note'];
+    const values = {};
+    for (const property of Reflect.ownKeys(input)) {
+        const descriptor = typeof property === 'string' ? Object.getOwnPropertyDescriptor(input, property) : undefined;
+        if (typeof property !== 'string' ||
+            !allowed.includes(property) ||
+            !descriptor?.enumerable ||
+            !('value' in descriptor)) {
+            throw new TypeError('Review metadata contains an unsupported or non-data property.');
+        }
+        values[property] = descriptor.value;
+    }
+    for (const key of ['locale', 'key', 'reviewer', 'status', 'reviewedAt']) {
+        if (!Object.hasOwn(values, key))
+            throw new TypeError(`Review field "${key}" is required.`);
+    }
+    for (const key of ['locale', 'key', 'reviewer']) {
+        const value = values[key];
+        if (typeof value !== 'string' || value.length < 1 || value.length > 256) {
+            throw new RangeError(`${key} must contain 1..256 characters.`);
+        }
+    }
+    if (!['draft', 'reviewed', 'approved', 'rejected'].includes(values.status)) {
+        throw new TypeError('status must be draft, reviewed, approved, or rejected.');
+    }
+    const timestamp = typeof values.reviewedAt === 'string' &&
+        /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/.test(values.reviewedAt)
+        ? Date.parse(values.reviewedAt)
+        : Number.NaN;
+    if (!Number.isFinite(timestamp) ||
+        new Date(timestamp).toISOString().slice(0, 19) !== values.reviewedAt.slice(0, 19)) {
+        throw new TypeError('reviewedAt must be an ISO timestamp ending in Z.');
+    }
+    if (values.note !== undefined && (typeof values.note !== 'string' || values.note.length > 2000)) {
+        throw new RangeError('note must be a string of at most 2000 characters.');
+    }
+    return Object.freeze({
+        locale: values.locale,
+        key: values.key,
+        reviewer: values.reviewer,
+        status: values.status,
+        reviewedAt: values.reviewedAt,
+        ...(values.note === undefined ? {} : { note: values.note }),
+    });
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/translation-workflow",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bounded translation catalog diffs, placeholder checks, and review metadata.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": "\u003e=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build \u0026\u0026 node scripts/check-types.mjs",
+    "test": "npm run build \u0026\u0026 node --test tests/*.test.mjs",
+    "format": "prettier --single-quote --write src scripts tests *.json README.md",
+    "format:check": "prettier --single-quote --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}