@vouchington/localization 0.0.1 → 0.1.0

package/README.md

@@ -2,15 +2,20 @@
 
 Browser-safe localization contracts for Node 24+ and browsers. The package owns locale
 normalization (`en` aliases `en-US`), exact and terminal-prefix selector validation, ordered
-fallback, consumer membership, and deterministic catalog serialization. It does not load catalogs,
-open SQLite, or interpolate message text.
+fallback, and deterministic catalog-table serialization. It does not load catalogs, open SQLite,
+or interpolate message text.
 
-Catalog shards on disk are a JSON array with **one compact message object per line**. `id` is the
-first key so git and line editors can add, remove, or update a message without parsing the file.
-`parseCatalogShardText` rejects pretty-printed JSON, `{ messages }` wrappers, and unsorted ids.
+Catalog source separates reusable copy from where each consumer renders it:
 
-`@vouchington/localization-compiler` compiles those shards into an immutable SQLite artifact,
-resolves the same selectors locally, and ships `upsert` / `remove` / `git-merge` for the line
-format. `git-merge` is 3-way: union independent ids, then merge consumers, descriptor, and
-each locale. Same-locale edits conflict and write `<<<<<<< ours` markers; adding `es` on one
-side and `fr` on the other does not.
+- `copies.json`: `{ id, descriptor }` rows.
+- `aliases.json`: `{ consumer, alias, copyId }` rows.
+- `translations/<locale>.json`: `{ id, value }` rows.
+- `routes.json` (generated): `{ consumer, selectorId, alias }` rows.
+
+A route selector resolves its generated membership independently of alias spelling, then returns
+the existing v1 alias-keyed wire response. Multiple aliases and consumers can therefore share one
+copy and its full translation variants.
+
+`@vouchington/localization-compiler` compiles those tables into an immutable SQLite artifact and
+resolves the same selectors locally. Its CLI owns table updates, formatting, CSV interchange, and
+three-way merges so catalog edits remain deterministic.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-export type { CatalogMessage, ExactSelector, LocalizationBatch, LocalizationBounds, LocalizationConsumer, LocalizationLeaf, LocalizationRequest, LocalizationSelector, LocalizationWireContract, MessageDescriptor, NormalizedLocalizationRequest, PluralCategory, PluralDescriptor, PluralForms, PrefixSelector, PublicLocalizationConsumer, SelectPluralCases, SelectPluralDescriptor, TranslationValue, } from './types.mts';
+export type { CatalogMessage, CatalogCopy, ConsumerAlias, ExactSelector, LocalizationBatch, LocalizationBounds, LocalizationConsumer, LocalizationLeaf, LocalizationRequest, LocalizationSelector, LocalizationWireContract, MessageDescriptor, NormalizedLocalizationRequest, PluralCategory, PluralDescriptor, PluralForms, PrefixSelector, PublicLocalizationConsumer, SelectPluralCases, SelectPluralDescriptor, TranslationValue, TranslationRow, RouteSelectorMembership, LocalizationCatalog, } from './types.mts';
+export { catalogFromMessages, catalogCopyFromRecord, consumerAliasFromRecord, translationRowFromRecord, routeSelectorMembershipFromRecord, serializeCatalogTable, } from './tables.mts';
 export { CANONICAL_SOURCE_LOCALE, ENGLISH_LOCALE_ALIAS, LOCALIZATION_CONSUMERS, LOCALIZATION_WIRE_CONTRACT, PLURAL_CATEGORIES, PUBLIC_LOCALIZATION_CONSUMERS, } from './types.mts';
 export { DEFAULT_LOCALIZATION_BOUNDS, LocalizationBoundError } from './bounds.mts';
 export { assertLocalizationConsumer, assertPublicLocalizationConsumer, isLocalizationConsumer, isPublicLocalizationConsumer, uniqueConsumers, } from './consumers.mts';

package/dist/index.mjs

@@ -1,3 +1,4 @@
+export { catalogFromMessages, catalogCopyFromRecord, consumerAliasFromRecord, translationRowFromRecord, routeSelectorMembershipFromRecord, serializeCatalogTable, } from './tables.mjs';
 export { CANONICAL_SOURCE_LOCALE, ENGLISH_LOCALE_ALIAS, LOCALIZATION_CONSUMERS, LOCALIZATION_WIRE_CONTRACT, PLURAL_CATEGORIES, PUBLIC_LOCALIZATION_CONSUMERS, } from './types.mjs';
 export { DEFAULT_LOCALIZATION_BOUNDS, LocalizationBoundError } from './bounds.mjs';
 export { assertLocalizationConsumer, assertPublicLocalizationConsumer, isLocalizationConsumer, isPublicLocalizationConsumer, uniqueConsumers, } from './consumers.mjs';

package/dist/tables.d.mts

@@ -0,0 +1,7 @@
+import type { CatalogCopy, CatalogMessage, ConsumerAlias, LocalizationCatalog, RouteSelectorMembership, TranslationRow } from './types.mts';
+export declare function catalogCopyFromRecord(value: unknown): CatalogCopy;
+export declare function consumerAliasFromRecord(value: unknown): ConsumerAlias;
+export declare function translationRowFromRecord(value: unknown): TranslationRow;
+export declare function routeSelectorMembershipFromRecord(value: unknown): RouteSelectorMembership;
+export declare function catalogFromMessages(messages: readonly CatalogMessage[]): LocalizationCatalog;
+export declare function serializeCatalogTable(rows: readonly unknown[]): string;

package/dist/tables.mjs

@@ -0,0 +1,70 @@
+import { uniqueConsumers } from './consumers.mjs';
+import { parseDescriptor } from './descriptors.mjs';
+import { compareCodePoints } from './compare.mjs';
+import { canonicalJson } from './serialize.mjs';
+import { isMessageId } from './selectors.mjs';
+export function catalogCopyFromRecord(value) {
+    if (!object(value) || typeof value.id !== 'string' || !isMessageId(value.id)) {
+        throw new TypeError('Copy is missing a valid id');
+    }
+    return { id: value.id, descriptor: parseDescriptor(value.descriptor ?? null) };
+}
+export function consumerAliasFromRecord(value) {
+    if (!object(value) || typeof value.alias !== 'string' || !isMessageId(value.alias)) {
+        throw new TypeError('Alias is missing a valid alias');
+    }
+    if (typeof value.copyId !== 'string' || !isMessageId(value.copyId)) {
+        throw new TypeError(`Alias "${value.alias}" is missing a valid copyId`);
+    }
+    return {
+        consumer: uniqueConsumers([String(value.consumer)])[0],
+        alias: value.alias,
+        copyId: value.copyId,
+    };
+}
+export function translationRowFromRecord(value) {
+    if (!object(value) ||
+        typeof value.id !== 'string' ||
+        !isMessageId(value.id) ||
+        !('value' in value)) {
+        throw new TypeError('Translation is missing a valid id or value');
+    }
+    return { id: value.id, value: value.value };
+}
+export function routeSelectorMembershipFromRecord(value) {
+    if (!object(value) || typeof value.selectorId !== 'string' || !isMessageId(value.selectorId)) {
+        throw new TypeError('Route membership is missing a valid selectorId');
+    }
+    if (typeof value.alias !== 'string' || !isMessageId(value.alias)) {
+        throw new TypeError('Route membership is missing a valid alias');
+    }
+    return {
+        consumer: uniqueConsumers([String(value.consumer)])[0],
+        selectorId: value.selectorId,
+        alias: value.alias,
+    };
+}
+export function catalogFromMessages(messages) {
+    const copies = messages.map(({ id, descriptor }) => ({ id, descriptor }));
+    const aliases = messages.flatMap(({ id, consumers }) => consumers.map((consumer) => ({ consumer, alias: id, copyId: id })));
+    const translations = {};
+    for (const message of messages)
+        for (const [locale, value] of Object.entries(message.translations)) {
+            ;
+            (translations[locale] ??= []).push({ id: message.id, value });
+        }
+    return { copies, aliases, translations };
+}
+export function serializeCatalogTable(rows) {
+    return `${canonicalJson([...rows].toSorted((a, b) => compareCodePoints(rowKey(a), rowKey(b))))}\n`;
+}
+function rowKey(value) {
+    if (!object(value))
+        return '';
+    return ['consumer', 'selectorId', 'alias', 'id']
+        .map((key) => (typeof value[key] === 'string' ? value[key] : ''))
+        .join('\t');
+}
+function object(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/types.d.mts

@@ -41,6 +41,36 @@ export type CatalogMessage = Readonly<{
     consumers: readonly LocalizationConsumer[];
     translations: Readonly<Record<string, TranslationValue>>;
 }>;
+/** Canonical, reusable copy. Its id is deliberately unrelated to any rendered slot. */
+export type CatalogCopy = Readonly<{
+    id: string;
+    descriptor: MessageDescriptor | null;
+}>;
+/** A consumer-owned rendered slot pointing at canonical copy. */
+export type ConsumerAlias = Readonly<{
+    consumer: LocalizationConsumer;
+    alias: string;
+    copyId: string;
+}>;
+/** One locale value for one canonical copy. */
+export type TranslationRow = Readonly<{
+    id: string;
+    value: TranslationValue;
+}>;
+/** Generated route closure membership. selectorId is not required to resemble an alias. */
+export type RouteSelectorMembership = Readonly<{
+    consumer: LocalizationConsumer;
+    selectorId: string;
+    alias: string;
+}>;
+/** The three source tables plus optional generated route membership and editorial tags. */
+export type LocalizationCatalog = Readonly<{
+    copies: readonly CatalogCopy[];
+    aliases: readonly ConsumerAlias[];
+    translations: Readonly<Record<string, readonly TranslationRow[]>>;
+    routeMembership?: readonly RouteSelectorMembership[];
+    tags?: Readonly<Record<string, readonly string[]>>;
+}>;
 export type LocalizationRequest = Readonly<{
     consumer: LocalizationConsumer;
     locales: readonly string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vouchington/localization",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Browser-safe localization catalog contracts, locale fallback, and selector validation.",
   "homepage": "https://github.com/vouchington/vouchington-platform/tree/main/packages/localization#readme",
   "bugs": {