smartloc 1.2.2 → 2.0.0

package/src/core/default-locale.tsx

@@ -0,0 +1,54 @@
+import { ILocaleDef, LocLiteral, ILiteralLocalizer } from './interfaces';
+import { LiteralLocalizer } from './literal';
+import { getLocale } from './locale-list';
+import { asFragment, autoGenerateId, getLocaleCode } from './utils';
+import React from 'react';
+
+const emptyStringAutoId = autoGenerateId([]);
+export class DefaultLocale implements ILocaleDef {
+
+    readonly literals: ILiteralLocalizer;
+    readonly code: string | undefined;
+
+    constructor(readonly id: string) {
+        this.literals = new LiteralLocalizer(this);
+        this.code = getLocaleCode(id);
+    }
+
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: false): string;
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: true): React.ReactNode;
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: boolean): string | React.ReactNode {
+        const existing = getLocale(this.id);
+        if (existing) {
+            const exist = existing.localize(id, count, parts, placeholders, react);
+            if (exist) {
+                return exist;
+            }
+        }
+
+        if (!parts || !placeholders) {
+            // special case for empty string, which could not be translated.
+            if (id === emptyStringAutoId) {
+                return '';
+            }
+            throw new Error(`The smartloc string "${id}" cannot be translated to your default locale. It is likely that is has been deserialized. In order to support deserialized strings, you MUST load your default locale as a classic locale. nb: To generate your default locale translation file through smartloc CLI, use --generateDefault option`)
+        }
+
+        // fallback to the in-code translation
+        const result: React.ReactNode[] = [];
+
+        // interleave the literals with the placeholders
+        for (let i = 0; i < placeholders.length; i++) {
+            result.push(parts[i]);
+            result.push(this.literals.localize(placeholders[i], react));
+        }
+
+        // add the last literal
+        result.push(parts[parts.length - 1]);
+        if (react) {
+            // return a fragment having result as children
+            return asFragment(result);
+        }
+        return result.join('');
+    }
+}

package/src/core/interfaces.ts

@@ -0,0 +1,49 @@
+export type LocStr = InternalLocStr & React.ReactElement;
+
+export interface InternalLocStr {
+    /**
+     * Localizes this string. To be used within a @see withLocales scope to have an actual translation.
+     */
+    toString(locale?: string | ILocaleDef): string;
+    toJSON(): any;
+
+    /** Apply a transformation to the final translated text */
+    transform(transformer: (x: string) => string): LocStr;
+
+    /** React hook equivalent of .toString(), but which will updated when local changes */
+    useAsString(): string;
+}
+
+export type LocLiteral = string | number | Date | LocStr | React.ReactNode;
+export interface ILiteralLocalizer {
+    localize(data: LocLiteral, react: false): string;
+    localize(data: LocLiteral, react: true): React.ReactNode;
+    localize(data: LocLiteral, react: boolean): string | React.ReactNode;
+}
+
+export interface ILocaleDef {
+    readonly id: string;
+    readonly code: string | undefined;
+    readonly literals: ILiteralLocalizer;
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: false): string | null;
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: true): React.ReactNode | null;
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: boolean): string | React.ReactNode | null;
+}
+
+export type TranslationTarget = string | {
+    singular: string | null;
+    plural: string;
+}
+
+export type TranslationOf<T> = T extends LocStr ? string
+    : T extends Object ? { [K in keyof T]: TranslationOf<T[K]> }
+    : T extends (infer E)[] ? TranslationOf<E>[]
+    : T;
+
+
+export type StorableOf<T> = T extends LocStr ? Stored
+    : T extends Object ? { [K in keyof T]: StorableOf<T[K]> }
+    : T extends (infer E)[] ? StorableOf<E>[]
+    : T;
+
+type Stored = string | { [key: string]: string } | { i18n: string; data: any[]; count?: number } | LocStr; // LocStr is there in case nonDescriptive is 'skip'

package/{core/json-utils.js → src/core/json-utils.ts}

@@ -1,46 +1,48 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.translateInContext = exports.translateObject = exports.toJsonStorable = exports.toLocalizable = exports.jsonParseLocalized = void 0;
-const smartloc_1 = require("./smartloc");
-const moment_1 = __importDefault(require("moment"));
-const literal_1 = require("./literal");
+import { singleLoc, multiLoc, withSerializationContext, withLocales, SerializationContextOptions, smartLoc } from './smartloc';
+import { isLocStr } from './literal';
+import type { TranslationOf, StorableOf } from './interfaces';
+
 /**
  * Parse a JSON string where localized strings have been serialized in their non translated form
  */
-function jsonParseLocalized(value) {
+export function jsonParseLocalized(value: string) {
     const parsed = JSON.parse(value);
     return _toLocalizable(parsed, 50);
 }
-exports.jsonParseLocalized = jsonParseLocalized;
+
 /**
  * Transforms an object that has been deserialized from a non translated from to an object that is translatable
  */
-function toLocalizable(value) {
+export function toLocalizable(value: any) {
     return _toLocalizable(value, 50);
 }
-exports.toLocalizable = toLocalizable;
-function _toLocalizable(value, depth) {
+function _toLocalizable(value: any, depth: number): any {
     if (depth < 0) {
         throw new Error('This object is either too nested, or has cycles');
     }
     if (!value) {
         return value;
     }
+
     if (typeof value === 'string') {
         if (value.startsWith('i18n/single:')) {
-            return new smartloc_1.SingleLoc(value.substr('i18n/single:'.length));
+            return singleLoc(value.substr('i18n/single:'.length));
         }
         if (value.startsWith('i18n/id:')) {
-            return new smartloc_1.SmartLoc(value.substr('i18n/id:'.length), null, null);
+            return smartLoc({
+                id: value.substr('i18n/id:'.length),
+                count: undefined,
+                literals: null,
+                placeholders: null
+            });
         }
         return value;
     }
+
     if (typeof value !== 'object' || value instanceof Date) {
         return value;
     }
+
     // === handle arrays
     if (value instanceof Array) {
         const retArray = [];
@@ -58,18 +60,26 @@ function _toLocalizable(value, depth) {
     if (!keys.length) {
         return value;
     }
+
     // === handle smartloc with args
     if (keys.length === 2 && keys.includes('i18n') && keys.includes('data') && typeof value.i18n === 'string' && value.data instanceof Array) {
-        return new smartloc_1.SmartLoc(value.i18n, null, value.data);
-    }
+        return smartLoc({
+            id: value.i18n,
+            literals: null,
+            placeholders: value.data,
+            count: value.count
+        });
+    }
+
     // === handle multi
-    const ret = {};
+    const ret: Record<string, string> = {};
     if (!keys.some(x => !x.startsWith('i18n:'))) {
         for (const k of keys) {
             ret[k.substr('i18n:'.length)] = value[k];
         }
-        return new smartloc_1.MultiLoc(ret);
+        return multiLoc(ret);
     }
+
     // === handle plain object
     let changed = false;
     for (const k of keys) {
@@ -80,28 +90,29 @@ function _toLocalizable(value, depth) {
         ? ret
         : value;
 }
+
 /**
  * Transforms an object so it can be stored with localized strings in their non translated form
  * @returns Either a new copy of your object, or your object (if had no smarloc strings in it)
  */
-function toJsonStorable(value, options) {
-    return smartloc_1.withSerializationContext(() => _toJsonStorable(value, 50), options);
+export function toJsonStorable<T>(value: T, options?: SerializationContextOptions): StorableOf<T> {
+    return withSerializationContext(() => _toJsonStorable(value, 50), options);
 }
-exports.toJsonStorable = toJsonStorable;
+
 /** Translates an object to the given language */
-function translateObject(locales, object) {
+export function translateObject<T>(locales: string | string[], object: T): TranslationOf<T> {
     if (typeof locales === 'string') {
         locales = [locales];
     }
-    return smartloc_1.withLocales(locales, () => _toJsonStorable(object, 50));
+    return withLocales(locales, () => _toJsonStorable(object, 50));
 }
-exports.translateObject = translateObject;
+
 /** Translates an object according to the current context (call this when wrapped in withSerializationContext() or withLocales()) */
-function translateInContext(object) {
+export function translateInContext(object: any) {
     return _toJsonStorable(object, 50);
 }
-exports.translateInContext = translateInContext;
-function _toJsonStorable(v, depth) {
+
+function _toJsonStorable(v: any, depth: number) {
     if (depth < 0) {
         throw new Error('This object is either too nested, or has cycles');
     }
@@ -111,11 +122,11 @@ function _toJsonStorable(v, depth) {
     if (typeof v !== 'object') {
         return v;
     }
-    if (moment_1.default.isMoment(v) || moment_1.default.isDuration(v)) {
+    if (v instanceof Date) {
         return v;
     }
     if (v instanceof Array) {
-        let ret;
+        let ret: any[] | undefined = undefined;
         for (let i = 0; i < v.length; i++) {
             const p = _toJsonStorable(v[i], depth - 1);
             if (p !== v[i] && !ret) {
@@ -130,10 +141,11 @@ function _toJsonStorable(v, depth) {
         }
         return ret || v;
     }
-    if (literal_1.isLocStr(v)) {
+    if (isLocStr(v)) {
         return v.toJSON();
     }
-    const obj = {};
+
+    const obj: Record<string, any> = {};
     let diff = false;
     for (const [k, p] of Object.entries(v)) {
         const val = _toJsonStorable(p, depth - 1);
@@ -148,4 +160,3 @@ function _toJsonStorable(v, depth) {
     Object.setPrototypeOf(obj, Object.getPrototypeOf(v));
     return obj;
 }
-//# sourceMappingURL=json-utils.js.map

package/src/core/literal.ts

@@ -0,0 +1,66 @@
+import React from 'react';
+import { LocLiteral, LocStr, ILocaleDef, ILiteralLocalizer } from './interfaces';
+
+const locTag = Symbol('_localizable');
+export function isLocStr(data: any): data is LocStr {
+    return data && typeof data === 'object' && data[locTag];
+}
+
+export function setIsLoc(data: any) {
+    data[locTag] = true;
+    Object.freeze(data);
+}
+
+export class LiteralLocalizer implements ILiteralLocalizer {
+    private numbers: Intl.NumberFormat;
+    private dateTimeFormat: Intl.DateTimeFormat;
+    private dateFormat: Intl.DateTimeFormat;
+
+    constructor(private locale: ILocaleDef) {
+        this.numbers = new Intl.NumberFormat(locale.id);
+        // Format for dates with time (equivalent to moment's 'LLL')
+        this.dateTimeFormat = new Intl.DateTimeFormat(locale.id, {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric',
+            hour: 'numeric',
+            minute: 'numeric'
+        });
+        // Format for dates without time (equivalent to moment's 'LL')
+        this.dateFormat = new Intl.DateTimeFormat(locale.id, {
+            year: 'numeric',
+            month: 'long',
+            day: 'numeric'
+        });
+    }
+
+    localize(data: LocLiteral, react: false): string;
+    localize(data: LocLiteral, react: true): React.ReactNode;
+    localize(data: LocLiteral, react: boolean): string | React.ReactNode {
+        if (typeof data === 'string') {
+            return data;
+        }
+        if (typeof data === 'number') {
+            return this.numbers.format(data);
+        }
+        if (data instanceof Date) {
+            // Check if the date has a time component (non-zero hours or minutes)
+            if (data.getHours() || data.getMinutes()) {
+                return this.dateTimeFormat.format(data);
+            }
+            return this.dateFormat.format(data);
+        }
+        if (isLocStr(data)) {
+            return data.toString(this.locale);
+        }
+        if (react) {
+            return data as React.ReactNode;
+        } else {
+            if (isLocStr(data)) {
+                return data.toString(this.locale);
+            }
+            console.error(new Error('Cannot use React elements in LocStr elements when not used in a React renderer'));
+            return '';
+        }
+    }
+}

package/src/core/load.ts

@@ -0,0 +1,82 @@
+import { addLocale } from './locale-list';
+import type { TranslationTarget } from './interfaces';
+
+/**
+ * Loads a locale generated from CLI
+ * @param filePath The file path to load
+ * @param merge If true, then the translations will be merged with already existing translations.
+ */
+export function loadJsonLocale(obj: GroupedTranslation, merge?: boolean): void
+export function loadJsonLocale(url: string, merge?: boolean): Promise<void>
+export function loadJsonLocale(urlOrObj: string | GroupedTranslation, merge?: boolean) {
+    if (typeof urlOrObj === 'string') {
+        return fetch(urlOrObj).then(async response => {
+            if (!response.ok) {
+                throw new Error(`Failed to fetch ${urlOrObj}: ${response.statusText}`);
+            }
+            const text = await response.json();
+            if (typeof text !== 'object') {
+                throw new Error(`Expecting ${urlOrObj} to be a JSON object`);
+            }
+            return loadJsonLocale(text, merge);
+        });
+    }
+
+    const transformed = convertLocale(ungroupTranslation(urlOrObj));
+    addLocale(urlOrObj.targetLanguage, transformed, merge);
+}
+
+
+export interface CollectItem {
+    source?: TranslationTarget;
+    target?: TranslationTarget | null;
+    dirty?: boolean;
+}
+
+export interface CollectResult {
+    [id: string]: CollectItem;
+}
+
+export interface Translation {
+    resources: CollectResult;
+    sourceLanguage?: string;
+    targetLanguage: string;
+}
+
+
+export interface GroupedTranslation {
+    resources: { [namespace: string]: CollectResult };
+    sourceLanguage?: string;
+    targetLanguage: string;
+}
+
+
+export function ungroupTranslation(translation: GroupedTranslation): Translation {
+    const result: Translation = {
+        targetLanguage: translation.targetLanguage,
+        sourceLanguage: translation.sourceLanguage,
+        resources: {},
+    };
+    for (const [namespace, data] of Object.entries(translation.resources)) {
+        for (const [id, val] of Object.entries(data ?? {})) {
+            if (namespace === '$default') {
+                result.resources[id] = val;
+            } else {
+                result.resources[`${namespace}.${id}`] = val;
+            }
+        }
+    }
+    return result;
+}
+
+
+
+export function convertLocale(locale: Translation): { [key: string]: TranslationTarget } {
+    const ret: { [key: string]: TranslationTarget } = {};
+    for (const [k, v] of Object.entries(locale.resources)) {
+        if (v.target) {
+            ret[k] = v.target;
+        }
+    }
+    return ret;
+}

package/src/core/locale-list.ts

@@ -0,0 +1,128 @@
+import { ILocaleDef, TranslationTarget } from './interfaces';
+import { DefaultLocale } from './default-locale';
+import { Locale } from './locale';
+
+let locales: { [key: string]: Locale } = {};
+
+let defaultLocale: ILocaleDef | null = null;
+let currentLocale: ILocaleDef | null = null;
+
+/** Defines the locale used in code */
+export function setDefaultLocale(localeId: string) {
+    defaultLocale = new DefaultLocale(localeId);
+    currentLocale = defaultLocale;
+}
+
+export function changeLocale(locale: ILocaleDef | string, throwIfNotFound = true) {
+    const loc = typeof locale === 'string' ? getLocale(locale) : locale;
+    if (!loc) {
+        if (!throwIfNotFound) {
+            return 'not found';
+        }
+        throw new Error(`Locale '${locale}' not found. Please load it first`);
+    }
+    if (currentLocale === loc) {
+        return 'unchanged';
+    }
+    currentLocale = loc;
+    subs.forEach(sub => sub());
+    return 'changed';
+}
+
+const subs: Set<() => void> = new Set();
+export function subscribeToLocaleChange(callback: () => void) {
+    subs.add(callback);
+    return () => { subs.delete(callback); };
+}
+export function getCurrentLocale(noDefault?: false): ILocaleDef;
+export function getCurrentLocale(noDefault: true): ILocaleDef | null;
+export function getCurrentLocale(noDefault = false) {
+    if (currentLocale || noDefault) {
+        return currentLocale ?? null;
+    }
+    return getDefaultLocale();
+}
+
+export function getDefaultLocale() {
+    if (!defaultLocale) {
+        throw new Error('You must specify default locale via setDefaultLocale() before using localization');
+    }
+    return defaultLocale;
+}
+
+/** Resets all locales */
+export function clearLocales() {
+    locales = {};
+}
+
+/** Remove a locale */
+export function removeLocale(id: string) {
+    id = id.toLowerCase();
+    const existing = locales[id];
+    if (!existing) {
+        return;
+    }
+    delete locales[id];
+    const bl = baseLocale(id);
+    if (bl && locales[bl] === existing) {
+        delete locales[bl];
+    }
+}
+
+/**
+ * Adds translations
+ * @param id Locale ID (ex: 'en', or 'en-US')
+ * @param localeDef Translations (string id as key, formatted string as values - ex : {myId: 'Translated {0} text {1}'})
+ * @param merge If true, then the translations will be merged with already existing translations.
+ */
+export function addLocale(id: string, localeDef: { [id: string]: TranslationTarget }, merge?: boolean) {
+    id = id.toLowerCase();
+    let loc = locales[id];
+    if (loc) {
+        if (!merge) {
+            throw new Error(`There already is a locale '${id}' defined. Set the 'merge' argument to 'true' if you want to add translations`);
+        }
+        loc.localeDef = {
+            ...loc.localeDef,
+            ...localeDef,
+        };
+        return;
+    }
+    loc = locales[id] = new Locale(id, localeDef);
+    const bl = baseLocale(id);
+    if (bl && !locales[bl]) {
+        locales[bl] = loc;
+    }
+}
+
+export function getLocale(id: string): ILocaleDef | null {
+    if (!id) {
+        return null;
+    }
+    const found = locales[id];
+    if (found) {
+        return found;
+    }
+    // if given "en-US", then try to downgrade to a non specific language.
+    const bl = baseLocale(id);
+    return bl && locales[bl] || null;
+}
+
+function baseLocale(l: string) {
+    const m = /^([a-zA-Z]+)\-[a-zA-Z]+$/.exec(l);
+    return m?.[1] || null;
+}
+
+export function* listLocales() {
+    yield* Object.keys(locales);
+    if (defaultLocale) {
+        yield defaultLocale.id;
+    }
+}
+
+export function* listLocaleDefs(): IterableIterator<ILocaleDef> {
+    yield* Object.values(locales);
+    if (defaultLocale) {
+        yield defaultLocale;
+    }
+}

package/src/core/locale.tsx

@@ -0,0 +1,75 @@
+import { ILocaleDef, ILiteralLocalizer, LocLiteral, TranslationTarget } from './interfaces';
+import { LiteralLocalizer } from './literal';
+import React from 'react';
+import { asFragment, getLocaleCode } from './utils';
+
+export class Locale implements ILocaleDef {
+    readonly literals: ILiteralLocalizer;
+    readonly code: string | undefined;
+
+    constructor(readonly id: string, public localeDef: { [id: string]: TranslationTarget }) {
+        this.literals = new LiteralLocalizer(this);
+        this.code = getLocaleCode(id);
+    }
+
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react?: false): string | null;
+    localize(id: string, count: number | null, parts: TemplateStringsArray | null, placeholders: LocLiteral[] | null, react: true): React.ReactNode | null;
+    localize(id: string, count: number | null, _parts: TemplateStringsArray, placeholders: LocLiteral[], react?: boolean): string | React.ReactNode | null {
+        const templateObj = this.localeDef[id];
+        if (!templateObj) {
+            return null;
+        }
+        let template: string | undefined = undefined;
+        if (typeof templateObj === 'string') {
+            template = templateObj;
+        } else {
+            if (count === 1 && templateObj.singular) {
+                template = templateObj.singular;
+            } else {
+                template = templateObj.plural;
+            }
+        }
+        if (!react) {
+            // same, but faster
+            const literals = placeholders?.map(x => this.literals.localize(x, false));
+            return format(template, literals);
+        }
+
+
+        const ret: React.ReactNode[] = [];
+        // match all {N} in the template and replace them with the corresponding literal
+        const matches = template.matchAll(/\{(\d+)\}/g);
+        let currentIndex = 0;
+        for (const match of matches) {
+            const fromLast = template.substring(currentIndex, match.index);
+            if (fromLast) {
+                ret.push(fromLast);
+            }
+            const i = parseInt(match[1]);
+            const p = placeholders[i];
+            if (p) {
+                ret.push(this.literals.localize(p, true));
+            } else {
+                console.warn(`Placeholder {${i}} in template of ${id} for locale ${this.id} does not exist`);
+            }
+            currentIndex = match.index + match[0].length;
+        }
+        const fromLast = template.substring(currentIndex);
+        if (fromLast) {
+            ret.push(fromLast);
+        }
+        return asFragment(ret);
+    }
+}
+
+function format(str: string, args: string[]) {
+    if (!args || !args.length) {
+        return str;
+    }
+    return str.replace(/{(\d+)}/g, function (match, number) {
+        return typeof args[number] !== 'undefined'
+            ? args[number]
+            : match
+            ;
+    });
+}