@celema/verba 0.3.0

package/LICENSE.md

@@ -0,0 +1,9 @@
+# The MIT License (MIT)
+
+Copyright (c) 2026-present Celema developers and contributors
+
+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

@@ -0,0 +1,66 @@
+# Celema Verba — JavaScript runtime
+
+The browser half of [Celema Verba](../README.md): a dependency-free ESM
+runtime for catalogs exported by the PHP `Translator`. Verba's
+`JavascriptScanner` extracts the same eight calls from `.js`, `.ts`, `.jsx`,
+`.tsx`, `.svelte`, and `.vue` sources, so marked strings flow through
+`i18n:sync` exactly like PHP ones.
+
+## Usage
+
+Inline the payload from `Translator::exportMany()` server-side and boot once
+per page:
+
+```html
+<script id="verba-catalog" type="application/json">
+	{
+		"locale": "de",
+		"domains": [
+			{
+				"domain": "app",
+				"plural": "de",
+				"messages": { "Save": "Speichern" },
+				"contexts": { "menu": { "Open": "Öffnen" } }
+			}
+		]
+	}
+</script>
+```
+
+```js
+import { __, __n, __p, loadAndActivate } from '@celema/verba';
+
+loadAndActivate(); // reads #verba-catalog, returns null during SSR
+
+__('Save'); // 'Speichern'
+__p('menu', 'Open'); // 'Öffnen'
+__('Hello :name', { name: 'Ada' }); // named args only — no sprintf in JS
+__n(':count file', ':count files', 3); // ':count' is bound automatically
+```
+
+The semantics mirror PHP: bare `__`/`__n`/`__p`/`__np` walk the domain cascade
+in payload order, while `__d`/`__dn`/`__dp`/`__dnp` pin one domain. Context is
+an exact lookup axis, so a contextual miss never uses an uncontextual entry or a
+different context. Any miss falls back to the message id. With no translator
+active the functions return the interpolated id, so calls are safe during SSR
+and in tests. Use `load()` and `activate()` separately when the translator needs
+inspection or other setup before activation.
+
+During SSR, `loadAndActivate()` returns `null` because no DOM is available, so
+the global helpers use the source-id fallback. Do not call the module-global
+`activate()` from a request handler because concurrent requests could share
+translators. The helper API does not currently support request-local translated
+SSR.
+
+Only positional `sprintf` interpolation is PHP-only; strings shared with the
+frontend should use named `:placeholder` arguments.
+
+## Scripts
+
+- `pnpm test` runs the Vitest suite.
+- `pnpm check` type-checks and verifies formatting.
+- `pnpm build` emits ESM and type declarations to `dist/`.
+
+## License
+
+This project is licensed under the [MIT license](LICENSE.md).

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { type Args, interpolate } from './interpolate.js';
+export { type PluralRule, pluralRule } from './plurals.js';
+export { type Contexts, type DomainPayload, type Messages, type Payload, Translator, } from './translator.js';
+export { __, __d, __dn, __dnp, __dp, __n, __np, __p, activate, deactivate, load, loadAndActivate, translator, } from './verba.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { interpolate } from './interpolate.js';
+export { pluralRule } from './plurals.js';
+export { Translator, } from './translator.js';
+export { __, __d, __dn, __dnp, __dp, __n, __np, __p, activate, deactivate, load, loadAndActivate, translator, } from './verba.js';

package/dist/interpolate.d.ts

@@ -0,0 +1,8 @@
+export type Args = Record<string, string | number>;
+/**
+ * Fills named `:key` placeholders in a message template. Longer keys are
+ * replaced first and replacements are never re-scanned, mirroring PHP's
+ * strtr. An empty args object leaves the template untouched. Positional
+ * sprintf arguments are PHP-only; a stray `%s` passes through unchanged.
+ */
+export declare function interpolate(template: string, args?: Args): string;

package/dist/interpolate.js

@@ -0,0 +1,20 @@
+/**
+ * Fills named `:key` placeholders in a message template. Longer keys are
+ * replaced first and replacements are never re-scanned, mirroring PHP's
+ * strtr. An empty args object leaves the template untouched. Positional
+ * sprintf arguments are PHP-only; a stray `%s` passes through unchanged.
+ */
+export function interpolate(template, args = {}) {
+    const keys = Object.keys(args);
+    if (keys.length === 0) {
+        return template;
+    }
+    const pattern = keys
+        .sort((a, b) => b.length - a.length)
+        .map((key) => escape(':' + key))
+        .join('|');
+    return template.replace(new RegExp(pattern, 'g'), (token) => String(args[token.slice(1)]));
+}
+function escape(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/plurals.d.ts

@@ -0,0 +1,8 @@
+export type PluralRule = (n: number) => number;
+/**
+ * Returns the rule mapping a count to its zero-based plural form index —
+ * the same classic gettext formulas as the PHP runtime. Only the exceptions
+ * are listed; every other language falls through to the two-form `n !== 1`
+ * default. Region subtags are honored where they change the rule.
+ */
+export declare function pluralRule(key: string): PluralRule;

package/dist/plurals.js

@@ -0,0 +1,58 @@
+/**
+ * Returns the rule mapping a count to its zero-based plural form index —
+ * the same classic gettext formulas as the PHP runtime. Only the exceptions
+ * are listed; every other language falls through to the two-form `n !== 1`
+ * default. Region subtags are honored where they change the rule.
+ */
+export function pluralRule(key) {
+    const norm = key.toLowerCase().replaceAll('-', '_');
+    const lang = norm.split('_')[0];
+    if (norm === 'pt_br' || lang === 'fr') {
+        return (n) => (n > 1 ? 1 : 0);
+    }
+    if (['ja', 'ko', 'zh', 'vi', 'th', 'id', 'fa'].includes(lang)) {
+        return () => 0;
+    }
+    if (['ru', 'uk', 'be'].includes(lang)) {
+        return (n) => {
+            if (n % 10 === 1 && n % 100 !== 11) {
+                return 0;
+            }
+            if (n % 10 >= 2 && n % 10 <= 4 && !(n % 100 >= 12 && n % 100 <= 14)) {
+                return 1;
+            }
+            return 2;
+        };
+    }
+    if (lang === 'pl') {
+        return (n) => {
+            if (n === 1) {
+                return 0;
+            }
+            if (n % 10 >= 2 && n % 10 <= 4 && !(n % 100 >= 12 && n % 100 <= 14)) {
+                return 1;
+            }
+            return 2;
+        };
+    }
+    if (lang === 'cs' || lang === 'sk') {
+        return (n) => {
+            if (n === 1) {
+                return 0;
+            }
+            return n >= 2 && n <= 4 ? 1 : 2;
+        };
+    }
+    if (lang === 'ar') {
+        return (n) => {
+            if (n === 0 || n === 1 || n === 2) {
+                return n;
+            }
+            if (n % 100 >= 3 && n % 100 <= 10) {
+                return 3;
+            }
+            return n % 100 >= 11 ? 4 : 5;
+        };
+    }
+    return (n) => (n === 1 ? 0 : 1);
+}

package/dist/translator.d.ts

@@ -0,0 +1,39 @@
+import { type Args } from './interpolate.js';
+export type Messages = Record<string, string | string[]>;
+export type Contexts = Record<string, Messages>;
+export type DomainPayload = {
+    domain: string;
+    plural?: string;
+    messages?: Messages;
+    contexts?: Contexts;
+};
+export type Payload = {
+    locale?: string;
+    domains?: DomainPayload[];
+};
+/**
+ * Resolves messages for one locale across an ordered cascade of domains —
+ * the JavaScript mirror of the PHP Translator, fed by the payload that
+ * `Translator::exportMany()` produces. The first entry whose catalog holds
+ * a translation wins; a miss falls back to the message id itself. A domain
+ * may appear once per locale of the PHP-side fallback chain, each entry
+ * carrying its own plural rule, so walking entries in payload order
+ * resolves the same chain the PHP runtime does.
+ */
+export declare class Translator {
+    readonly locale: string;
+    private readonly domains;
+    constructor(payload?: Payload);
+    translate(id: string, args?: Args): string;
+    translateContext(context: string, id: string, args?: Args): string;
+    translateDomain(name: string, id: string, args?: Args): string;
+    translateDomainContext(name: string, context: string, id: string, args?: Args): string;
+    translatePlural(one: string, many: string, n: number, args?: Args): string;
+    translateContextPlural(context: string, one: string, many: string, n: number, args?: Args): string;
+    translateDomainPlural(name: string, one: string, many: string, n: number, args?: Args): string;
+    translateDomainContextPlural(name: string, context: string, one: string, many: string, n: number, args?: Args): string;
+    private translateFrom;
+    private translateDomainFrom;
+    private translatePluralFrom;
+    private translateDomainPluralFrom;
+}

package/dist/translator.js

@@ -0,0 +1,119 @@
+import { interpolate } from './interpolate.js';
+import { pluralRule } from './plurals.js';
+/**
+ * Resolves messages for one locale across an ordered cascade of domains —
+ * the JavaScript mirror of the PHP Translator, fed by the payload that
+ * `Translator::exportMany()` produces. The first entry whose catalog holds
+ * a translation wins; a miss falls back to the message id itself. A domain
+ * may appear once per locale of the PHP-side fallback chain, each entry
+ * carrying its own plural rule, so walking entries in payload order
+ * resolves the same chain the PHP runtime does.
+ */
+export class Translator {
+    locale;
+    domains;
+    constructor(payload = {}) {
+        this.locale = payload.locale ?? 'en';
+        this.domains = (payload.domains ?? []).map((entry) => ({
+            name: entry.domain,
+            messages: readMessages(entry.messages),
+            contexts: readContexts(entry.contexts),
+            rule: pluralRule(entry.plural ?? this.locale),
+        }));
+    }
+    translate(id, args = {}) {
+        return this.translateFrom(null, id, args);
+    }
+    translateContext(context, id, args = {}) {
+        return this.translateFrom(context, id, args);
+    }
+    translateDomain(name, id, args = {}) {
+        return this.translateDomainFrom(name, null, id, args);
+    }
+    translateDomainContext(name, context, id, args = {}) {
+        return this.translateDomainFrom(name, context, id, args);
+    }
+    translatePlural(one, many, n, args = {}) {
+        return this.translatePluralFrom(null, one, many, n, args);
+    }
+    translateContextPlural(context, one, many, n, args = {}) {
+        return this.translatePluralFrom(context, one, many, n, args);
+    }
+    translateDomainPlural(name, one, many, n, args = {}) {
+        return this.translateDomainPluralFrom(name, null, one, many, n, args);
+    }
+    translateDomainContextPlural(name, context, one, many, n, args = {}) {
+        return this.translateDomainPluralFrom(name, context, one, many, n, args);
+    }
+    translateFrom(context, id, args) {
+        for (const domain of this.domains) {
+            const entry = messageFrom(domain, context, id);
+            if (typeof entry === 'string') {
+                return interpolate(entry, args);
+            }
+        }
+        return interpolate(id, args);
+    }
+    translateDomainFrom(name, context, id, args) {
+        for (const domain of this.domains) {
+            if (domain.name !== name) {
+                continue;
+            }
+            const entry = messageFrom(domain, context, id);
+            if (typeof entry === 'string') {
+                return interpolate(entry, args);
+            }
+        }
+        return interpolate(id, args);
+    }
+    translatePluralFrom(context, one, many, n, args) {
+        for (const domain of this.domains) {
+            const form = pluralFrom(domain, context, one, n, args);
+            if (form !== null) {
+                return form;
+            }
+        }
+        return interpolate(n === 1 ? one : many, pluralArgs(args, n));
+    }
+    translateDomainPluralFrom(name, context, one, many, n, args) {
+        for (const domain of this.domains) {
+            if (domain.name !== name) {
+                continue;
+            }
+            const form = pluralFrom(domain, context, one, n, args);
+            if (form !== null) {
+                return form;
+            }
+        }
+        return interpolate(n === 1 ? one : many, pluralArgs(args, n));
+    }
+}
+/** PHP encodes an empty message map as a JSON array, so lists read as empty. */
+function readMessages(messages) {
+    return messages === undefined || Array.isArray(messages) ? {} : messages;
+}
+function readContexts(contexts) {
+    if (contexts === undefined || Array.isArray(contexts)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(contexts).map(([context, messages]) => [context, readMessages(messages)]));
+}
+function messageFrom(domain, context, id) {
+    return context === null ? domain.messages[id] : domain.contexts[context]?.[id];
+}
+/** An empty form list counts as untranslated, like a missing id — mirrors PHP. */
+function pluralFrom(domain, context, one, n, args) {
+    const entry = messageFrom(domain, context, one);
+    if (Array.isArray(entry) && entry.length > 0) {
+        const form = entry[domain.rule(n)] ?? entry[entry.length - 1];
+        return interpolate(form, pluralArgs(args, n));
+    }
+    if (typeof entry === 'string') {
+        return interpolate(entry, pluralArgs(args, n));
+    }
+    return null;
+}
+/** Binds `:count` to the count unless the caller already set it. */
+function pluralArgs(args, n) {
+    return 'count' in args ? args : { ...args, count: n };
+}

package/dist/verba.d.ts

@@ -0,0 +1,33 @@
+import type { Args } from './interpolate.js';
+import { Translator } from './translator.js';
+/**
+ * Wires the global functions to a translator. With no translator active,
+ * lookups return the message id (with interpolation), which keeps
+ * translation calls safe during SSR, in tests, and before boot.
+ */
+export declare function activate(translator: Translator): void;
+export declare function deactivate(): void;
+export declare function translator(): Translator | null;
+/**
+ * Reads the JSON payload inlined in the given script element and wraps it in
+ * a Translator. Returns null without a DOM (SSR), when the element is
+ * missing or empty, or when its content is not valid JSON.
+ */
+export declare function load(elementId?: string): Translator | null;
+export declare function loadAndActivate(elementId?: string): Translator | null;
+/** Translate a message through the active domain cascade. */
+export declare function __(id: string, args?: Args): string;
+/** Translate a contextual message through the active domain cascade. */
+export declare function __p(context: string, id: string, args?: Args): string;
+/** Translate a pluralized message, choosing the form for n. */
+export declare function __n(one: string, many: string, n: number, args?: Args): string;
+/** Translate a contextual pluralized message, choosing the form for n. */
+export declare function __np(context: string, one: string, many: string, n: number, args?: Args): string;
+/** Translate a message from a specific domain. */
+export declare function __d(domain: string, id: string, args?: Args): string;
+/** Translate a contextual message from a specific domain. */
+export declare function __dp(domain: string, context: string, id: string, args?: Args): string;
+/** Translate a pluralized message from a specific domain. */
+export declare function __dn(domain: string, one: string, many: string, n: number, args?: Args): string;
+/** Translate a contextual pluralized message from a specific domain. */
+export declare function __dnp(domain: string, context: string, one: string, many: string, n: number, args?: Args): string;

package/dist/verba.js

@@ -0,0 +1,76 @@
+import { Translator } from './translator.js';
+let active = null;
+let fallback = null;
+/**
+ * Wires the global functions to a translator. With no translator active,
+ * lookups return the message id (with interpolation), which keeps
+ * translation calls safe during SSR, in tests, and before boot.
+ */
+export function activate(translator) {
+    active = translator;
+}
+export function deactivate() {
+    active = null;
+}
+export function translator() {
+    return active;
+}
+/**
+ * Reads the JSON payload inlined in the given script element and wraps it in
+ * a Translator. Returns null without a DOM (SSR), when the element is
+ * missing or empty, or when its content is not valid JSON.
+ */
+export function load(elementId = 'verba-catalog') {
+    const el = typeof document === 'undefined' ? null : document.getElementById(elementId);
+    if (!el?.textContent) {
+        return null;
+    }
+    try {
+        return new Translator(JSON.parse(el.textContent));
+    }
+    catch {
+        return null;
+    }
+}
+export function loadAndActivate(elementId) {
+    const loaded = load(elementId);
+    if (loaded) {
+        activate(loaded);
+    }
+    return loaded;
+}
+/** Translate a message through the active domain cascade. */
+export function __(id, args = {}) {
+    return current().translate(id, args);
+}
+/** Translate a contextual message through the active domain cascade. */
+export function __p(context, id, args = {}) {
+    return current().translateContext(context, id, args);
+}
+/** Translate a pluralized message, choosing the form for n. */
+export function __n(one, many, n, args = {}) {
+    return current().translatePlural(one, many, n, args);
+}
+/** Translate a contextual pluralized message, choosing the form for n. */
+export function __np(context, one, many, n, args = {}) {
+    return current().translateContextPlural(context, one, many, n, args);
+}
+/** Translate a message from a specific domain. */
+export function __d(domain, id, args = {}) {
+    return current().translateDomain(domain, id, args);
+}
+/** Translate a contextual message from a specific domain. */
+export function __dp(domain, context, id, args = {}) {
+    return current().translateDomainContext(domain, context, id, args);
+}
+/** Translate a pluralized message from a specific domain. */
+export function __dn(domain, one, many, n, args = {}) {
+    return current().translateDomainPlural(domain, one, many, n, args);
+}
+/** Translate a contextual pluralized message from a specific domain. */
+export function __dnp(domain, context, one, many, n, args = {}) {
+    return current().translateDomainContextPlural(domain, context, one, many, n, args);
+}
+function current() {
+    return active ?? (fallback ??= new Translator());
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@celema/verba",
+  "version": "0.3.0",
+  "description": "JavaScript runtime for Celema Verba translation catalogs",
+  "license": "MIT",
+  "homepage": "https://celema.dev/verba",
+  "repository": {
+    "type": "git",
+    "url": "git+https://codeberg.org/celema/verba.git",
+    "directory": "js"
+  },
+  "keywords": [
+    "celema",
+    "internationalization",
+    "i18n",
+    "gettext"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "prettier": "^3.9.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "check": "tsc && prettier --check .",
+    "format": "prettier --write .",
+    "test": "vitest run"
+  }
+}