@vouchington/localization 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Ong
+
+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 ANY 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

@@ -0,0 +1,9 @@
+# @vouchington/localization
+
+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.
+
+`@vouchington/localization-compiler` compiles namespace-sharded JSON into an immutable SQLite
+artifact and resolves the same selectors locally.

package/dist/bounds.d.mts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_LOCALIZATION_BOUNDS: {
+    readonly maxLocales: 8;
+    readonly maxSelectors: 32;
+    readonly maxMessages: 2000;
+    readonly maxBytes: number;
+};
+export declare class LocalizationBoundError extends RangeError {
+    readonly code = "LOCALIZATION_BOUNDS";
+}

package/dist/bounds.mjs

@@ -0,0 +1,9 @@
+export const DEFAULT_LOCALIZATION_BOUNDS = {
+    maxLocales: 8,
+    maxSelectors: 32,
+    maxMessages: 2000,
+    maxBytes: 512 * 1024,
+};
+export class LocalizationBoundError extends RangeError {
+    code = 'LOCALIZATION_BOUNDS';
+}

package/dist/catalog.d.mts

@@ -0,0 +1,3 @@
+import type { CatalogMessage } from './types.mts';
+export declare function serializeCatalogMessages(messages: readonly CatalogMessage[]): string;
+export declare function catalogMessageFromRecord(value: unknown): CatalogMessage;

package/dist/catalog.mjs

@@ -0,0 +1,34 @@
+import { uniqueConsumers } from './consumers.mjs';
+import { parseDescriptor } from './descriptors.mjs';
+import { canonicalJson } from './serialize.mjs';
+import { isMessageId } from './selectors.mjs';
+export function serializeCatalogMessages(messages) {
+    return canonicalJson([...messages]
+        .toSorted((left, right) => (left.id < right.id ? -1 : 1))
+        .map((message) => ({
+        consumers: uniqueConsumers(message.consumers),
+        descriptor: message.descriptor,
+        id: message.id,
+        translations: message.translations,
+    })));
+}
+export function catalogMessageFromRecord(value) {
+    if (!isPlainObject(value) || typeof value.id !== 'string' || !isMessageId(value.id)) {
+        throw new TypeError('Catalog message is missing a valid id');
+    }
+    if (!Array.isArray(value.consumers) || value.consumers.length === 0) {
+        throw new TypeError(`Catalog message "${value.id}" must declare consumers`);
+    }
+    if (!isPlainObject(value.translations) || Object.keys(value.translations).length === 0) {
+        throw new TypeError(`Catalog message "${value.id}" must declare translations`);
+    }
+    return {
+        id: value.id,
+        descriptor: parseDescriptor(value.descriptor ?? null),
+        consumers: uniqueConsumers(value.consumers.map(String)),
+        translations: value.translations,
+    };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/compare.d.mts

@@ -0,0 +1 @@
+export declare function compareCodePoints(left: string, right: string): number;

package/dist/compare.mjs

@@ -0,0 +1,3 @@
+export function compareCodePoints(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}

package/dist/consumers.d.mts

@@ -0,0 +1,6 @@
+import { type LocalizationConsumer, type PublicLocalizationConsumer } from './types.mts';
+export declare function isLocalizationConsumer(value: string): value is LocalizationConsumer;
+export declare function isPublicLocalizationConsumer(value: string): value is PublicLocalizationConsumer;
+export declare function assertLocalizationConsumer(value: string): LocalizationConsumer;
+export declare function assertPublicLocalizationConsumer(value: string): PublicLocalizationConsumer;
+export declare function uniqueConsumers(values: readonly string[]): readonly LocalizationConsumer[];

package/dist/consumers.mjs

@@ -0,0 +1,26 @@
+import { LOCALIZATION_CONSUMERS, PUBLIC_LOCALIZATION_CONSUMERS, } from './types.mjs';
+export function isLocalizationConsumer(value) {
+    return LOCALIZATION_CONSUMERS.includes(value);
+}
+export function isPublicLocalizationConsumer(value) {
+    return PUBLIC_LOCALIZATION_CONSUMERS.includes(value);
+}
+export function assertLocalizationConsumer(value) {
+    if (!isLocalizationConsumer(value)) {
+        throw new TypeError(`Unknown localization consumer "${value}"`);
+    }
+    return value;
+}
+export function assertPublicLocalizationConsumer(value) {
+    const consumer = assertLocalizationConsumer(value);
+    if (!isPublicLocalizationConsumer(consumer)) {
+        throw new TypeError(`Localization consumer "${value}" is not public`);
+    }
+    return consumer;
+}
+export function uniqueConsumers(values) {
+    const seen = new Set();
+    for (const value of values)
+        seen.add(assertLocalizationConsumer(value));
+    return LOCALIZATION_CONSUMERS.filter((consumer) => seen.has(consumer));
+}

package/dist/descriptors.d.mts

@@ -0,0 +1,6 @@
+import { type MessageDescriptor, type PluralForms, type TranslationValue } from './types.mts';
+export declare function isPluralForms(value: unknown): value is PluralForms;
+export declare function isSelectPluralCases(value: unknown): value is Readonly<Record<string, PluralForms>>;
+export declare function isTranslationValue(value: unknown): value is TranslationValue;
+export declare function descriptorSignature(descriptor: MessageDescriptor): string;
+export declare function parseDescriptor(value: unknown): MessageDescriptor | null;

package/dist/descriptors.mjs

@@ -0,0 +1,81 @@
+import { compareCodePoints } from './compare.mjs';
+import { PLURAL_CATEGORIES, } from './types.mjs';
+const PLURAL_KEYS = new Set(PLURAL_CATEGORIES);
+export function isPluralForms(value) {
+    if (!isPlainObject(value) || typeof value.other !== 'string')
+        return false;
+    return Object.entries(value).every(([key, form]) => PLURAL_KEYS.has(key) && typeof form === 'string');
+}
+export function isSelectPluralCases(value) {
+    return (isPlainObject(value) &&
+        Object.keys(value).length > 0 &&
+        Object.values(value).every(isPluralForms));
+}
+export function isTranslationValue(value) {
+    return typeof value === 'string' || isPluralForms(value) || isSelectPluralCases(value);
+}
+export function descriptorSignature(descriptor) {
+    return JSON.stringify({
+        kind: descriptor.kind,
+        valueParameter: descriptor.valueParameter,
+        selectParameter: descriptor.kind === 'select-plural' ? descriptor.selectParameter : null,
+        numberParameters: [...(descriptor.numberParameters ?? [])].toSorted(compareCodePoints),
+        cases: descriptor.kind === 'select-plural' ? [...descriptor.cases].toSorted(compareCodePoints) : [],
+    });
+}
+export function parseDescriptor(value) {
+    if (value === null)
+        return null;
+    if (!isPlainObject(value) ||
+        typeof value.kind !== 'string' ||
+        typeof value.valueParameter !== 'string') {
+        throw new TypeError('Invalid message descriptor');
+    }
+    const numberParameters = optionalStringArray(value.numberParameters);
+    if (value.kind === 'plural') {
+        assertNoKeys(value, ['kind', 'valueParameter', 'numberParameters']);
+        return numberParameters === undefined
+            ? { kind: 'plural', valueParameter: value.valueParameter }
+            : { kind: 'plural', valueParameter: value.valueParameter, numberParameters };
+    }
+    if (value.kind !== 'select-plural' || typeof value.selectParameter !== 'string') {
+        throw new TypeError('Invalid message descriptor');
+    }
+    const cases = value.cases;
+    if (!Array.isArray(cases) ||
+        cases.length === 0 ||
+        cases.some((item) => typeof item !== 'string')) {
+        throw new TypeError('Invalid select-plural descriptor cases');
+    }
+    assertNoKeys(value, ['kind', 'valueParameter', 'selectParameter', 'numberParameters', 'cases']);
+    return numberParameters === undefined
+        ? {
+            kind: 'select-plural',
+            valueParameter: value.valueParameter,
+            selectParameter: value.selectParameter,
+            cases: [...cases],
+        }
+        : {
+            kind: 'select-plural',
+            valueParameter: value.valueParameter,
+            selectParameter: value.selectParameter,
+            numberParameters,
+            cases: [...cases],
+        };
+}
+function optionalStringArray(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((item) => typeof item !== 'string')) {
+        throw new TypeError('Descriptor numberParameters must be a string array');
+    }
+    return [...value];
+}
+function assertNoKeys(value, allowed) {
+    if (Object.keys(value).some((key) => !allowed.includes(key))) {
+        throw new TypeError('Invalid message descriptor');
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+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 { 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';
+export { aliasEnglishLocale, canonicalizeLocale, normalizeLocale, normalizeLocaleList, } from './locales.mts';
+export { dedupeSelectors, isMessageId, parseSelector, prefixRange, selectorMatches, } from './selectors.mts';
+export { assertMessageCount, assertPayloadBytes, normalizeLocalizationRequest } from './request.mts';
+export { firstAvailableTranslation, leafForTranslation, selectedIds } from './selection.mts';
+export { assertSamePlaceholders, placeholdersIn, uniquePlaceholders } from './placeholders.mts';
+export { descriptorSignature, isPluralForms, isSelectPluralCases, isTranslationValue, parseDescriptor, } from './descriptors.mts';
+export { canonicalJson } from './serialize.mts';
+export { compareCodePoints } from './compare.mts';
+export { catalogMessageFromRecord, serializeCatalogMessages } from './catalog.mts';
+export { createLocalizationBatch, etagMatches, localizationEtag, serializeLocalizationBatch, } from './wire.mts';

package/dist/index.mjs

@@ -0,0 +1,13 @@
+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';
+export { aliasEnglishLocale, canonicalizeLocale, normalizeLocale, normalizeLocaleList, } from './locales.mjs';
+export { dedupeSelectors, isMessageId, parseSelector, prefixRange, selectorMatches, } from './selectors.mjs';
+export { assertMessageCount, assertPayloadBytes, normalizeLocalizationRequest } from './request.mjs';
+export { firstAvailableTranslation, leafForTranslation, selectedIds } from './selection.mjs';
+export { assertSamePlaceholders, placeholdersIn, uniquePlaceholders } from './placeholders.mjs';
+export { descriptorSignature, isPluralForms, isSelectPluralCases, isTranslationValue, parseDescriptor, } from './descriptors.mjs';
+export { canonicalJson } from './serialize.mjs';
+export { compareCodePoints } from './compare.mjs';
+export { catalogMessageFromRecord, serializeCatalogMessages } from './catalog.mjs';
+export { createLocalizationBatch, etagMatches, localizationEtag, serializeLocalizationBatch, } from './wire.mjs';

package/dist/locales.d.mts

@@ -0,0 +1,5 @@
+export declare function canonicalizeLocale(value: string): string | null;
+/** Maps `en` onto `en-US` after Unicode canonicalization. */
+export declare function aliasEnglishLocale(value: string): string;
+export declare function normalizeLocale(value: string): string | null;
+export declare function normalizeLocaleList(values: readonly string[], available?: readonly string[] | null): string[];

package/dist/locales.mjs

@@ -0,0 +1,38 @@
+import { CANONICAL_SOURCE_LOCALE, ENGLISH_LOCALE_ALIAS } from './types.mjs';
+const LANGUAGE_TAG = /^[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*$/;
+export function canonicalizeLocale(value) {
+    const trimmed = value.trim().replaceAll('_', '-');
+    if (!LANGUAGE_TAG.test(trimmed))
+        return null;
+    try {
+        return Intl.getCanonicalLocales(trimmed)[0] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Maps `en` onto `en-US` after Unicode canonicalization. */
+export function aliasEnglishLocale(value) {
+    return value === ENGLISH_LOCALE_ALIAS ? CANONICAL_SOURCE_LOCALE : value;
+}
+export function normalizeLocale(value) {
+    const canonical = canonicalizeLocale(value);
+    return canonical === null ? null : aliasEnglishLocale(canonical);
+}
+export function normalizeLocaleList(values, available = null) {
+    const allowed = available === null ? null : new Set(available.map(aliasEnglishLocale));
+    const locales = [];
+    const seen = new Set();
+    for (const value of values) {
+        const locale = normalizeLocale(value);
+        if (locale === null)
+            throw new TypeError(`Invalid locale "${value}"`);
+        if (allowed !== null && !allowed.has(locale))
+            continue;
+        if (seen.has(locale))
+            continue;
+        seen.add(locale);
+        locales.push(locale);
+    }
+    return locales;
+}

package/dist/placeholders.d.mts

@@ -0,0 +1,3 @@
+export declare function placeholdersIn(value: string): string[];
+export declare function uniquePlaceholders(values: readonly string[]): string[];
+export declare function assertSamePlaceholders(canonical: readonly string[], other: readonly string[], path: string): void;

package/dist/placeholders.mjs

@@ -0,0 +1,13 @@
+import { compareCodePoints } from './compare.mjs';
+const PLACEHOLDER = /\{([\w.-]+)\}/g;
+export function placeholdersIn(value) {
+    return [...value.matchAll(PLACEHOLDER)].map((match) => match[1]).toSorted(compareCodePoints);
+}
+export function uniquePlaceholders(values) {
+    return [...new Set(values.flatMap(placeholdersIn))].toSorted(compareCodePoints);
+}
+export function assertSamePlaceholders(canonical, other, path) {
+    if (canonical.join(',') !== other.join(',')) {
+        throw new TypeError(`Placeholder mismatch at "${path}"`);
+    }
+}

package/dist/request.d.mts

@@ -0,0 +1,4 @@
+import type { LocalizationBounds, LocalizationRequest, NormalizedLocalizationRequest } from './types.mts';
+export declare function normalizeLocalizationRequest(request: LocalizationRequest, availableLocales?: readonly string[] | null, bounds?: LocalizationBounds): NormalizedLocalizationRequest;
+export declare function assertMessageCount(count: number, bounds: LocalizationBounds): void;
+export declare function assertPayloadBytes(payload: string, bounds: LocalizationBounds): void;

package/dist/request.mjs

@@ -0,0 +1,38 @@
+import { LocalizationBoundError, DEFAULT_LOCALIZATION_BOUNDS } from './bounds.mjs';
+import { assertLocalizationConsumer } from './consumers.mjs';
+import { normalizeLocaleList } from './locales.mjs';
+import { dedupeSelectors, parseSelector } from './selectors.mjs';
+export function normalizeLocalizationRequest(request, availableLocales = null, bounds = DEFAULT_LOCALIZATION_BOUNDS) {
+    const consumer = assertLocalizationConsumer(request.consumer);
+    if (request.locales.length === 0)
+        throw new TypeError('At least one locale is required');
+    if (request.locales.length > bounds.maxLocales) {
+        throw new LocalizationBoundError(`At most ${bounds.maxLocales} locales are allowed`);
+    }
+    if (request.selectors.length === 0)
+        throw new TypeError('At least one selector is required');
+    if (request.selectors.length > bounds.maxSelectors) {
+        throw new LocalizationBoundError(`At most ${bounds.maxSelectors} selectors are allowed`);
+    }
+    const locales = normalizeLocaleList(request.locales, availableLocales);
+    if (locales.length === 0)
+        throw new TypeError('No requested locales are available');
+    return {
+        consumer,
+        locales,
+        selectors: dedupeSelectors(request.selectors.map(parseSelector)),
+    };
+}
+export function assertMessageCount(count, bounds) {
+    if (count > bounds.maxMessages) {
+        throw new LocalizationBoundError(`At most ${bounds.maxMessages} messages are allowed`);
+    }
+}
+export function assertPayloadBytes(payload, bounds) {
+    if (byteLength(payload) > bounds.maxBytes) {
+        throw new LocalizationBoundError(`Localization payload exceeds ${bounds.maxBytes} bytes`);
+    }
+}
+function byteLength(value) {
+    return new TextEncoder().encode(value).byteLength;
+}

package/dist/selection.d.mts

@@ -0,0 +1,4 @@
+import type { LocalizationLeaf, LocalizationSelector, MessageDescriptor, TranslationValue } from './types.mts';
+export declare function selectedIds(ids: readonly string[], selectors: readonly LocalizationSelector[]): string[];
+export declare function firstAvailableTranslation(locales: readonly string[], translations: Readonly<Record<string, TranslationValue>>): TranslationValue | undefined;
+export declare function leafForTranslation(descriptor: MessageDescriptor | null, value: TranslationValue): LocalizationLeaf;

package/dist/selection.mjs

@@ -0,0 +1,53 @@
+import { compareCodePoints } from './compare.mjs';
+import { selectorMatches } from './selectors.mjs';
+export function selectedIds(ids, selectors) {
+    return ids
+        .filter((id) => selectors.some((selector) => selectorMatches(selector, id)))
+        .toSorted(compareCodePoints);
+}
+export function firstAvailableTranslation(locales, translations) {
+    for (const locale of locales) {
+        if (Object.hasOwn(translations, locale))
+            return translations[locale];
+    }
+    return undefined;
+}
+export function leafForTranslation(descriptor, value) {
+    if (descriptor === null) {
+        if (typeof value !== 'string')
+            throw new TypeError('String messages require string translations');
+        return value;
+    }
+    if (descriptor.kind === 'plural') {
+        if (!isPluralForms(value))
+            throw new TypeError('Plural messages require plural-form translations');
+        return descriptor.numberParameters === undefined
+            ? { kind: 'plural', valueParameter: descriptor.valueParameter, forms: value }
+            : {
+                kind: 'plural',
+                valueParameter: descriptor.valueParameter,
+                numberParameters: descriptor.numberParameters,
+                forms: value,
+            };
+    }
+    if (typeof value === 'string' || isPluralForms(value)) {
+        throw new TypeError('Select-plural messages require cased translations');
+    }
+    return descriptor.numberParameters === undefined
+        ? {
+            kind: 'select-plural',
+            valueParameter: descriptor.valueParameter,
+            selectParameter: descriptor.selectParameter,
+            cases: value,
+        }
+        : {
+            kind: 'select-plural',
+            valueParameter: descriptor.valueParameter,
+            selectParameter: descriptor.selectParameter,
+            numberParameters: descriptor.numberParameters,
+            cases: value,
+        };
+}
+function isPluralForms(value) {
+    return (typeof value === 'object' && Object.hasOwn(value, 'other') && typeof value.other === 'string');
+}

package/dist/selectors.d.mts

@@ -0,0 +1,6 @@
+import type { LocalizationSelector } from './types.mts';
+export declare function isMessageId(value: string): boolean;
+export declare function parseSelector(value: string): LocalizationSelector;
+export declare function selectorMatches(selector: LocalizationSelector, id: string): boolean;
+export declare function prefixRange(prefix: string): readonly [string, string];
+export declare function dedupeSelectors(selectors: readonly LocalizationSelector[]): LocalizationSelector[];

package/dist/selectors.mjs

@@ -0,0 +1,52 @@
+import { compareCodePoints } from './compare.mjs';
+const SEGMENT = '[A-Za-z0-9][A-Za-z0-9_-]*';
+const MESSAGE_ID = new RegExp(`^${SEGMENT}(?:\\.${SEGMENT})+$`);
+const PREFIX_SELECTOR = new RegExp(`^${SEGMENT}(?:\\.${SEGMENT})*\\.\\*$`);
+export function isMessageId(value) {
+    return MESSAGE_ID.test(value);
+}
+export function parseSelector(value) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError('Localization selector must be a non-empty string');
+    }
+    if (PREFIX_SELECTOR.test(value))
+        return { kind: 'prefix', prefix: value.slice(0, -2) };
+    if (MESSAGE_ID.test(value))
+        return { kind: 'exact', id: value };
+    throw new TypeError(`Invalid localization selector "${value}"`);
+}
+export function selectorMatches(selector, id) {
+    return selector.kind === 'exact' ? selector.id === id : id.startsWith(`${selector.prefix}.`);
+}
+export function prefixRange(prefix) {
+    return [`${prefix}.`, `${prefix}/`];
+}
+export function dedupeSelectors(selectors) {
+    const prefixes = uniquePrefixes(selectors.filter(isPrefix));
+    const exact = new Map();
+    for (const selector of selectors) {
+        if (selector.kind !== 'exact')
+            continue;
+        if (prefixes.some((prefix) => selectorMatches(prefix, selector.id)))
+            continue;
+        exact.set(selector.id, selector);
+    }
+    return [
+        ...prefixes,
+        ...[...exact.values()].toSorted((left, right) => compareCodePoints(left.id, right.id)),
+    ];
+}
+function uniquePrefixes(selectors) {
+    const sorted = selectors.toSorted((left, right) => compareCodePoints(left.prefix, right.prefix));
+    const prefixes = [];
+    for (const selector of sorted) {
+        if (prefixes.some((prefix) => selector.prefix === prefix.prefix || selector.prefix.startsWith(`${prefix.prefix}.`))) {
+            continue;
+        }
+        prefixes.push(selector);
+    }
+    return prefixes;
+}
+function isPrefix(selector) {
+    return selector.kind === 'prefix';
+}

package/dist/serialize.d.mts

@@ -0,0 +1 @@
+export declare function canonicalJson(value: unknown): string;

package/dist/serialize.mjs

@@ -0,0 +1,29 @@
+import { compareCodePoints } from './compare.mjs';
+export function canonicalJson(value) {
+    return stringify(sort(value));
+}
+function sort(value) {
+    if (Array.isArray(value))
+        return value.map(sort);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .toSorted(([left], [right]) => compareCodePoints(left, right))
+        .map(([key, nested]) => [key, sort(nested)]));
+}
+function stringify(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return JSON.stringify(value);
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(stringify).join(',')}]`;
+    if (typeof value === 'object') {
+        return `{${Object.entries(value)
+            .map(([key, nested]) => `${JSON.stringify(key)}:${stringify(nested)}`)
+            .join(',')}}`;
+    }
+    throw new TypeError('Cannot serialize localization value');
+}

package/dist/types.d.mts

@@ -0,0 +1,70 @@
+export declare const LOCALIZATION_CONSUMERS: readonly ['web', 'swift', 'dotnet', 'email'];
+export declare const PUBLIC_LOCALIZATION_CONSUMERS: readonly ['web', 'swift', 'dotnet'];
+export declare const LOCALIZATION_WIRE_CONTRACT: 'v1';
+export declare const CANONICAL_SOURCE_LOCALE: 'en-US';
+export declare const ENGLISH_LOCALE_ALIAS: 'en';
+export declare const PLURAL_CATEGORIES: readonly ['zero', 'one', 'two', 'few', 'many', 'other'];
+export type LocalizationConsumer = (typeof LOCALIZATION_CONSUMERS)[number];
+export type PublicLocalizationConsumer = (typeof PUBLIC_LOCALIZATION_CONSUMERS)[number];
+export type LocalizationWireContract = typeof LOCALIZATION_WIRE_CONTRACT;
+export type PluralCategory = (typeof PLURAL_CATEGORIES)[number];
+export type PluralForms = Readonly<{
+    other: string;
+} & Partial<Record<PluralCategory, string>>>;
+export type SelectPluralCases = Readonly<Record<string, PluralForms>>;
+export type TranslationValue = string | PluralForms | SelectPluralCases;
+export type PluralDescriptor = Readonly<{
+    kind: 'plural';
+    valueParameter: string;
+    numberParameters?: readonly string[];
+}>;
+export type SelectPluralDescriptor = Readonly<{
+    kind: 'select-plural';
+    valueParameter: string;
+    selectParameter: string;
+    numberParameters?: readonly string[];
+    cases: readonly string[];
+}>;
+export type MessageDescriptor = PluralDescriptor | SelectPluralDescriptor;
+export type ExactSelector = Readonly<{
+    kind: 'exact';
+    id: string;
+}>;
+export type PrefixSelector = Readonly<{
+    kind: 'prefix';
+    prefix: string;
+}>;
+export type LocalizationSelector = ExactSelector | PrefixSelector;
+export type CatalogMessage = Readonly<{
+    id: string;
+    descriptor: MessageDescriptor | null;
+    consumers: readonly LocalizationConsumer[];
+    translations: Readonly<Record<string, TranslationValue>>;
+}>;
+export type LocalizationRequest = Readonly<{
+    consumer: LocalizationConsumer;
+    locales: readonly string[];
+    selectors: readonly string[];
+}>;
+export type NormalizedLocalizationRequest = Readonly<{
+    consumer: LocalizationConsumer;
+    locales: readonly string[];
+    selectors: readonly LocalizationSelector[];
+}>;
+export type LocalizationBounds = Readonly<{
+    maxLocales: number;
+    maxSelectors: number;
+    maxMessages: number;
+    maxBytes: number;
+}>;
+export type LocalizationLeaf = string | Readonly<PluralDescriptor & {
+    forms: PluralForms;
+}> | Readonly<Omit<SelectPluralDescriptor, 'cases'> & {
+    cases: SelectPluralCases;
+}>;
+export type LocalizationBatch = Readonly<{
+    contract: LocalizationWireContract;
+    revision: string;
+    ttlSeconds: number;
+    messages: Readonly<Record<string, LocalizationLeaf>>;
+}>;

package/dist/types.mjs

@@ -0,0 +1,6 @@
+export const LOCALIZATION_CONSUMERS = ['web', 'swift', 'dotnet', 'email'];
+export const PUBLIC_LOCALIZATION_CONSUMERS = ['web', 'swift', 'dotnet'];
+export const LOCALIZATION_WIRE_CONTRACT = 'v1';
+export const CANONICAL_SOURCE_LOCALE = 'en-US';
+export const ENGLISH_LOCALE_ALIAS = 'en';
+export const PLURAL_CATEGORIES = ['zero', 'one', 'two', 'few', 'many', 'other'];

package/dist/wire.d.mts

@@ -0,0 +1,5 @@
+import type { LocalizationBatch, LocalizationLeaf } from './types.mts';
+export declare function serializeLocalizationBatch(batch: LocalizationBatch): string;
+export declare function localizationEtag(revision: string): string;
+export declare function etagMatches(header: string | null | undefined, revision: string): boolean;
+export declare function createLocalizationBatch(revision: string, ttlSeconds: number, messages: Readonly<Record<string, LocalizationLeaf>>): LocalizationBatch;

package/dist/wire.mjs

@@ -0,0 +1,33 @@
+import { compareCodePoints } from './compare.mjs';
+import { LOCALIZATION_WIRE_CONTRACT } from './types.mjs';
+import { canonicalJson } from './serialize.mjs';
+export function serializeLocalizationBatch(batch) {
+    return canonicalJson({
+        contract: batch.contract,
+        messages: Object.fromEntries(Object.entries(batch.messages).toSorted(([left], [right]) => compareCodePoints(left, right))),
+        revision: batch.revision,
+        ttlSeconds: batch.ttlSeconds,
+    });
+}
+export function localizationEtag(revision) {
+    return `"${revision}"`;
+}
+export function etagMatches(header, revision) {
+    if (header == null || header.trim() === '')
+        return false;
+    const expected = localizationEtag(revision);
+    return header
+        .split(',')
+        .some((value) => value.trim() === expected || value.trim() === `W/${expected}`);
+}
+export function createLocalizationBatch(revision, ttlSeconds, messages) {
+    if (!Number.isInteger(ttlSeconds) || ttlSeconds <= 0) {
+        throw new TypeError('ttlSeconds must be a positive integer');
+    }
+    return {
+        contract: LOCALIZATION_WIRE_CONTRACT,
+        revision,
+        ttlSeconds,
+        messages: Object.fromEntries(Object.entries(messages).toSorted(([left], [right]) => compareCodePoints(left, right))),
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@vouchington/localization",
+  "version": "0.0.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": {
+    "url": "https://github.com/vouchington/vouchington-platform/issues"
+  },
+  "license": "MIT",
+  "author": "Jonathan Ong",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vouchington/vouchington-platform.git",
+    "directory": "packages/localization"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "prepack": "pnpm run build"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}