@ayinza_dev/i18n-config 1.4.1 → 1.5.1

package/dist/config.js

@@ -57,6 +57,7 @@ const mergeFormatters = (base, override) => {
             ...override?.date,
         },
         fallbackLocale: override?.fallbackLocale ?? base?.fallbackLocale,
+        numberingSystem: override?.numberingSystem ?? base?.numberingSystem,
     };
 };
 function mergeConfig(base, override) {

package/dist/formatters.d.ts

@@ -4,9 +4,16 @@ export declare class I18nFormatters {
     private numberConfig;
     private dateConfig;
     private fallbackLocale;
+    private numberingSystem;
     private normalizeLanguage;
     constructor(config?: FormattersConfig);
     private getLocale;
+    /**
+     * Force a numbering system across every Intl formatter (incl. RelativeTime,
+     * which has no `numberingSystem` option) by appending the Unicode `-u-nu-`
+     * locale extension. No-op when disabled or already present.
+     */
+    private applyNumberingSystem;
     /**
      * Format with locale-specific formatting
      */

package/dist/formatters.js

@@ -21,6 +21,10 @@ export class I18nFormatters {
     constructor(config = {}) {
         this.fallbackLocale =
             config.fallbackLocale || defaultLocaleMapping.en || "en-US";
+        // Default to Western (latn) digits so localized output keeps native words
+        // (month/weekday/currency labels) and RTL but renders 0-9. `??` (not `||`)
+        // so an explicit "" opts back into each locale's native numbering.
+        this.numberingSystem = config.numberingSystem ?? "latn";
         this.currencyConfig = {
             defaultCurrency: config.currency?.defaultCurrency || "USD",
             localeMapping: {
@@ -48,7 +52,19 @@ export class I18nFormatters {
     }
     getLocale(language, mapping) {
         const { full, base } = this.normalizeLanguage(language);
-        return mapping[full] || mapping[base] || this.fallbackLocale;
+        const locale = mapping[full] || mapping[base] || this.fallbackLocale;
+        return this.applyNumberingSystem(locale);
+    }
+    /**
+     * Force a numbering system across every Intl formatter (incl. RelativeTime,
+     * which has no `numberingSystem` option) by appending the Unicode `-u-nu-`
+     * locale extension. No-op when disabled or already present.
+     */
+    applyNumberingSystem(locale) {
+        if (!this.numberingSystem || locale.includes("-u-nu-")) {
+            return locale;
+        }
+        return `${locale}-u-nu-${this.numberingSystem}`;
     }
     /**
      * Format with locale-specific formatting

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { I18nConfig, I18nInitOptions, FormattersConfig, LocaleMapping, Pars
 export { I18nFormatters } from "./formatters.js";
 export { useFormatting, useI18n } from "./hooks.js";
 export { createI18nextParserConfig } from "./parser-config.js";
-export { createTranslationSnapshot, collectNewTranslationKeys, handleNewTranslationKeys, } from "./parser-hooks.js";
+export { createTranslationSnapshot, collectNewTranslationKeys, handleNewTranslationKeys, publishTranslationOverrides, resolveSourcePushUrl, resolveOverridePushUrl, TRANSLATE_SEND_PATH, ADMIN_TRANSLATIONS_PATH, } from "./parser-hooks.js";
+export type { PublishTranslationOverridesOptions } from "./parser-hooks.js";
 export { useTranslation, Trans, Translation } from "react-i18next";
 export { type TFunction } from "i18next";

package/dist/index.js

@@ -2,6 +2,6 @@ export { initializeI18n, getI18nInstance, getFormatters, defaultConfig, createI1
 export { I18nFormatters } from "./formatters.js";
 export { useFormatting, useI18n } from "./hooks.js";
 export { createI18nextParserConfig } from "./parser-config.js";
-export { createTranslationSnapshot, collectNewTranslationKeys, handleNewTranslationKeys, } from "./parser-hooks.js";
+export { createTranslationSnapshot, collectNewTranslationKeys, handleNewTranslationKeys, publishTranslationOverrides, resolveSourcePushUrl, resolveOverridePushUrl, TRANSLATE_SEND_PATH, ADMIN_TRANSLATIONS_PATH, } from "./parser-hooks.js";
 // Re-export commonly used utilities from react-i18next
 export { useTranslation, Trans, Translation } from "react-i18next";

package/dist/parser-hooks.d.ts

@@ -1,4 +1,27 @@
 import type { NewKeyPayload, ParserPushConfig, TranslationSnapshot } from "./types.js";
+/**
+ * Localization-service endpoint paths, appended to the API base URL
+ * (`VITE_LOCALIZATION_API_BASE_URL`, e.g. `https://…/api/v1`). Owning them here is
+ * the single source of truth so no consumer hardcodes (and mis-types) the paths —
+ * the override route in particular lives under `/l10n/admin/translations`, NOT the
+ * bare `/admin/translations`.
+ */
+export declare const TRANSLATE_SEND_PATH = "/l10n/translate/send";
+export declare const ADMIN_TRANSLATIONS_PATH = "/l10n/admin/translations";
+/**
+ * Build the source-key registration URL (POST) from an API base URL — the
+ * `pushUrl` for {@link handleNewTranslationKeys}.
+ *
+ * @example resolveSourcePushUrl("https://loc/api/v1") // ".../api/v1/l10n/translate/send"
+ */
+export declare const resolveSourcePushUrl: (apiBaseUrl: string) => string;
+/**
+ * Build the human-override collection URL from an API base URL — the `pushUrl`
+ * for {@link publishTranslationOverrides}, which appends `/{locale}` per request.
+ *
+ * @example resolveOverridePushUrl("https://loc/api/v1") // ".../api/v1/l10n/admin/translations"
+ */
+export declare const resolveOverridePushUrl: (apiBaseUrl: string) => string;
 export interface CreateTranslationSnapshotOptions {
     locale: string;
     namespaces: Record<string, Record<string, unknown>>;
@@ -21,3 +44,24 @@ export interface HandleNewTranslationKeysResult {
 export declare const createTranslationSnapshot: (options: CreateTranslationSnapshotOptions) => TranslationSnapshot;
 export declare const collectNewTranslationKeys: (options: CollectNewTranslationKeysOptions) => NewKeyPayload[];
 export declare const handleNewTranslationKeys: (options: HandleNewTranslationKeysOptions) => Promise<HandleNewTranslationKeysResult>;
+export interface PublishTranslationOverridesOptions {
+    /** Target locale whose values are being corrected, e.g. `ar-SA`. */
+    locale: string;
+    /** Flat `key -> corrected value` map. Only keys present are overridden. */
+    translations: Record<string, string>;
+    /**
+     * Push settings. `pushUrl` is the override collection endpoint (e.g.
+     * `${base}/l10n/admin/translations`); the locale is appended per request.
+     */
+    pushConfig: ParserPushConfig;
+    requestInit?: RequestInit;
+    logger?: Pick<Console, "log" | "warn" | "error">;
+}
+/**
+ * Publish curated translation overrides for a locale to the localization
+ * service's upsert endpoint (`PUT /l10n/admin/translations/{locale}`). Any Ayinza
+ * product uses this to correct its own catalog (e.g. replacing garbled machine
+ * translations); the service marks the rows human-authoritative so the MT
+ * sweep never re-manufactures them.
+ */
+export declare const publishTranslationOverrides: (options: PublishTranslationOverridesOptions) => Promise<HandleNewTranslationKeysResult>;

package/dist/parser-hooks.js

@@ -1,3 +1,27 @@
+/**
+ * Localization-service endpoint paths, appended to the API base URL
+ * (`VITE_LOCALIZATION_API_BASE_URL`, e.g. `https://…/api/v1`). Owning them here is
+ * the single source of truth so no consumer hardcodes (and mis-types) the paths —
+ * the override route in particular lives under `/l10n/admin/translations`, NOT the
+ * bare `/admin/translations`.
+ */
+export const TRANSLATE_SEND_PATH = "/l10n/translate/send";
+export const ADMIN_TRANSLATIONS_PATH = "/l10n/admin/translations";
+const stripTrailingSlashes = (url) => url.replace(/\/+$/, "");
+/**
+ * Build the source-key registration URL (POST) from an API base URL — the
+ * `pushUrl` for {@link handleNewTranslationKeys}.
+ *
+ * @example resolveSourcePushUrl("https://loc/api/v1") // ".../api/v1/l10n/translate/send"
+ */
+export const resolveSourcePushUrl = (apiBaseUrl) => `${stripTrailingSlashes(apiBaseUrl)}${TRANSLATE_SEND_PATH}`;
+/**
+ * Build the human-override collection URL from an API base URL — the `pushUrl`
+ * for {@link publishTranslationOverrides}, which appends `/{locale}` per request.
+ *
+ * @example resolveOverridePushUrl("https://loc/api/v1") // ".../api/v1/l10n/admin/translations"
+ */
+export const resolveOverridePushUrl = (apiBaseUrl) => `${stripTrailingSlashes(apiBaseUrl)}${ADMIN_TRANSLATIONS_PATH}`;
 const formatValue = (value) => {
     if (value === undefined || value === null) {
         return "";
@@ -76,31 +100,22 @@ const headersToRecord = (headers) => {
     }
     return { ...headers };
 };
-export const handleNewTranslationKeys = async (options) => {
-    const { newKeys, pushConfig, requestInit, logger = console } = options;
-    const dryRun = pushConfig.dryRun || !pushConfig.pushUrl;
-    if (!newKeys.length) {
-        logger.log(`🗒️  No new translation keys for ${pushConfig.portalName}.`);
-        return { pushed: 0, dryRun };
-    }
-    const translations = {};
-    for (const keyEntry of newKeys) {
-        translations[keyEntry.key] = keyEntry.defaultValue;
-    }
+/**
+ * Send a `{ data: { translations, category? } }` catalog payload to the
+ * localization-service. Shared by the source-key push (POST /translate/send)
+ * and the override publish (PUT /l10n/admin/translations/{locale}).
+ */
+const sendCatalogPayload = async (options) => {
+    const { url, method, translations, pushConfig, requestInit } = options;
     const payload = {
         data: {
             translations,
-            // Tag every pushed key with the producer's category when configured so
+            // Tag the payload with the producer's category when configured so
             // consumers can fetch a scoped catalog. Omitted entirely when unset to
             // preserve the un-categorised (shared) default.
             ...(pushConfig.category ? { category: pushConfig.category } : {}),
         },
     };
-    if (dryRun) {
-        logger.log(`💡 Dry run for ${pushConfig.portalName}:\n` +
-            newKeys.map((key) => ` • ${key.namespace}:${key.key}`).join("\n"));
-        return { pushed: 0, dryRun: true };
-    }
     const fetchImpl = pushConfig.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
         throw new Error("No fetch implementation available. Provide pushConfig.fetchImpl in non-Node 18 environments.");
@@ -113,17 +128,74 @@ export const handleNewTranslationKeys = async (options) => {
         headerBag.Authorization = `Bearer ${pushConfig.authorizationToken}`;
     }
     Object.assign(headerBag, headersToRecord(requestInit?.headers));
-    const init = {
+    const response = await fetchImpl(url, {
         ...requestInit,
-        method: "POST",
+        method,
         body: JSON.stringify(payload),
         headers: headerBag,
-    };
-    const response = await fetchImpl(pushConfig.pushUrl, init);
+    });
     if (!response.ok) {
         const errorBody = await response.text().catch(() => "");
-        throw new Error(`Failed to push new translation keys (${response.status}): ${errorBody}`);
+        throw new Error(`Failed to ${method} translations (${response.status}): ${errorBody}`);
+    }
+};
+export const handleNewTranslationKeys = async (options) => {
+    const { newKeys, pushConfig, requestInit, logger = console } = options;
+    const dryRun = pushConfig.dryRun || !pushConfig.pushUrl;
+    if (!newKeys.length) {
+        logger.log(`🗒️  No new translation keys for ${pushConfig.portalName}.`);
+        return { pushed: 0, dryRun };
+    }
+    const translations = {};
+    for (const keyEntry of newKeys) {
+        translations[keyEntry.key] = keyEntry.defaultValue;
     }
+    if (dryRun) {
+        logger.log(`💡 Dry run for ${pushConfig.portalName}:\n` +
+            newKeys.map((key) => ` • ${key.namespace}:${key.key}`).join("\n"));
+        return { pushed: 0, dryRun: true };
+    }
+    await sendCatalogPayload({
+        url: pushConfig.pushUrl,
+        method: "POST",
+        translations,
+        pushConfig,
+        requestInit,
+    });
     logger.log(`✅ Pushed ${newKeys.length} keys for ${pushConfig.portalName}.`);
     return { pushed: newKeys.length, dryRun: false };
 };
+/**
+ * Publish curated translation overrides for a locale to the localization
+ * service's upsert endpoint (`PUT /l10n/admin/translations/{locale}`). Any Ayinza
+ * product uses this to correct its own catalog (e.g. replacing garbled machine
+ * translations); the service marks the rows human-authoritative so the MT
+ * sweep never re-manufactures them.
+ */
+export const publishTranslationOverrides = async (options) => {
+    const { locale, translations, pushConfig, requestInit, logger = console } = options;
+    const count = Object.keys(translations).length;
+    const dryRun = pushConfig.dryRun || !pushConfig.pushUrl;
+    if (!count) {
+        logger.log(`🗒️  No translation overrides for ${pushConfig.portalName}.`);
+        return { pushed: 0, dryRun };
+    }
+    if (dryRun) {
+        logger.log(`💡 Dry run for ${pushConfig.portalName} (${locale}):\n` +
+            Object.keys(translations)
+                .map((key) => ` • ${key}`)
+                .join("\n"));
+        return { pushed: 0, dryRun: true };
+    }
+    const base = pushConfig.pushUrl.replace(/\/+$/, "");
+    const url = `${base}/${encodeURIComponent(locale)}`;
+    await sendCatalogPayload({
+        url,
+        method: "PUT",
+        translations,
+        pushConfig,
+        requestInit,
+    });
+    logger.log(`✅ Published ${count} ${locale} overrides for ${pushConfig.portalName}.`);
+    return { pushed: count, dryRun: false };
+};

package/dist/types.d.ts

@@ -21,6 +21,15 @@ export interface FormattersConfig {
     date?: DateConfig;
     /** Locale to fall back to when a language code is missing from mappings. */
     fallbackLocale?: string;
+    /**
+     * Unicode numbering system applied to all number/date/currency/percent/
+     * relative-time output via the locale's `-u-nu-` extension. Defaults to
+     * `"latn"` (Western 0-9 digits) so locales like `ar-SA` keep Arabic words
+     * (month/weekday names, currency labels) and RTL while rendering Western
+     * digits — the common convention for finance/tax UIs. Set to `"arab"` for
+     * Eastern Arabic numerals, or `""` to use each locale's native digits.
+     */
+    numberingSystem?: string;
 }
 export interface ReactConfig {
     useSuspense?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayinza_dev/i18n-config",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",