smartloc 1.2.1 → 2.0.0

package/src/core/smartloc.tsx

@@ -0,0 +1,338 @@
+import { getLocale, getDefaultLocale, getCurrentLocale, subscribeToLocaleChange, listLocaleDefs } from './locale-list';
+import { ILocaleDef, InternalLocStr, LocLiteral, LocStr } from './interfaces';
+import { setIsLoc } from './literal';
+import React, { useState } from 'react';
+import { asFragment } from './utils';
+
+let langCtx: ILocaleDef[] | null = null;
+let serialContext: SerializationContextOptions | null = null;
+
+export function useAsString(loc: LocStr | string | null): string | null;
+export function useAsString(loc: LocStr | string | undefined): string | undefined;
+export function useAsString(loc: LocStr | string | undefined): string | undefined;
+export function useAsString(loc: LocStr | string | null | undefined): string | null | undefined {
+    const [, setCount] = useState(0);
+    React.useEffect(() => {
+        const unsub = subscribeToLocaleChange(() => setCount(c => c + 1));
+        return unsub;
+    }, []);
+    return loc?.toString();
+}
+
+
+export interface SerializationContextOptions {
+    /** HOw non self-descriptive (MultiLoc, SingleLoc, ...) will be transformed. Defaults to 'id'.
+     *
+     * id => will serialize its ID ... the context of deserialization will be required to have the given translation
+     * skip => will be left as it (=> serialization will translate it)
+     * toMulti => translates to all registered languages, and serializes as a 'multi'
+     */
+    nonSelfDescriptive?: 'skip' | 'toMulti' | 'id';
+}
+/**
+ * Execute something in the given locales context.
+ * @param acceptLanguages The accepted languages, by order of preference
+ * @param action Action to perform (usually a JSON.serialize() or a .toString() operation)
+ **/
+export function withLocales<T = void>(acceptLanguages: string[], action: () => T) {
+    if (!acceptLanguages || !acceptLanguages.length) {
+        return action();
+    }
+    const oldLangCtx = langCtx;
+    try {
+        // set accepted languages
+        langCtx = acceptLanguages
+            .map(getLocale)
+            .filter(x => !!x);
+
+        // perform action
+        return action();
+    } finally {
+        langCtx = oldLangCtx;
+    }
+}
+
+/**
+ * Execute something in a context where .toJson() loc strings
+ * will be serialized into a form that is parsable via jsonParseLocalized()
+ */
+export function withSerializationContext<T = void>(action: () => T, options?: SerializationContextOptions) {
+    const os = serialContext;
+    try {
+        serialContext = options || {};
+        return action();
+    } finally {
+        serialContext = os;
+    }
+}
+
+
+interface SmartlocProps {
+    id: string,
+    literals: TemplateStringsArray | null;
+    placeholders: LocLiteral[] | null;
+    count: number | undefined;
+}
+
+function createKind<props extends object>(opts: {
+    name: string;
+    render: (props: props, locale: ILocaleDef) => React.ReactNode | null;
+    toString: (props: props, locale: ILocaleDef) => string | null;
+    toJson: (props: props) => any;
+}) {
+
+    const Renderer = {
+        [opts.name]: class extends React.Component<props, { locale: ILocaleDef | null }> {
+            private rerender = () => this.setState({
+                locale: getCurrentLocale(),
+            });
+            private unsub?: () => void;
+
+            override componentDidMount(): void {
+                this.unsub = subscribeToLocaleChange(this.rerender);
+
+            }
+
+            override componentWillUnmount() {
+                this.unsub?.();
+            }
+
+            override render(): React.ReactNode {
+                const locale = this.state?.locale;
+                if (locale) {
+                    const rendered = opts.render(this.props, locale);
+                    if (rendered) {
+                        return rendered;
+                    }
+                }
+                const currentLocale = getCurrentLocale(true);
+                if (currentLocale) {
+                    const rendered = opts.render(this.props, currentLocale);
+                    if (rendered) {
+                        return rendered;
+                    }
+                }
+                const defaultLocale = getDefaultLocale();
+                if (defaultLocale) {
+                    const rendered = opts.render(this.props, defaultLocale);
+                    if (rendered) {
+                        return rendered;
+                    }
+                }
+                return null;
+            }
+        },
+    }[opts.name];
+
+    const Proto = {
+        [opts.name]: class implements InternalLocStr {
+            get locKind() {
+                return opts.name;
+            }
+            // will be set the hackky way, see creator below
+            props!: props;
+
+            toJSON() {
+                if (!serialContext) {
+                    return this.toString();
+                }
+                return opts.toJson(this.props);
+            }
+
+            toString(locale?: string | ILocaleDef | null): string {
+                if (typeof locale === 'string') {
+                    locale = getLocale(locale);
+                }
+
+                if (locale) {
+                    const localized = opts.toString(this.props, locale)
+                    if (localized) {
+                        return localized;
+                    }
+                }
+                if (langCtx?.length) {
+                    for (const l of langCtx) {
+                        const localized = opts.toString(this.props, l);
+                        if (localized) {
+                            return localized;
+                        }
+                    }
+                }
+
+                // try current locale
+                const currentLocale = getCurrentLocale(true);
+                if (currentLocale) {
+                    const localized = opts.toString(this.props, currentLocale);
+                    if (localized) {
+                        return localized;
+                    }
+                }
+
+                // fallback to default locale
+                const defaultLocale = getDefaultLocale();
+                if (!defaultLocale) {
+                    throw new Error('You must specify default locale via setDefaultLocale() before using localization');
+                }
+                // default locale cannot return null
+                const def = opts.toString(this.props, defaultLocale);
+                if (!def) {
+                    throw new Error('Cannot get a translation'); // should not happen
+                }
+                return def;
+            }
+
+            transform(transformer: (x: string) => string): LocStr {
+                return transformed({
+                    parent: this,
+                    transformer,
+                });
+            }
+
+            useAsString(): string {
+                const [, setCount] = useState(0);
+                React.useEffect(() => {
+                    const unsub = subscribeToLocaleChange(() => setCount(c => c + 1));
+                    return unsub;
+                }, []);
+                return this.toString();
+            }
+        }
+    }[opts.name];
+
+
+
+    // trick to create a function that is named like the given name
+    const creator = {
+        [opts.name](props: props): LocStr {
+            const e = React.createElement(Renderer, props);
+            const eProps = Object.getOwnPropertyDescriptors(e);
+            const ret = Object.create(Proto.prototype);
+            Object.defineProperties(ret, eProps);
+            setIsLoc(ret); // this will freeze the object
+            return ret;
+        }
+    }[opts.name];
+
+    return creator;
+}
+
+
+
+export const smartLoc = createKind<SmartlocProps>({
+    name: 'SmartLoc',
+    render(props, locale) {
+        return locale.localize(props.id, props.count ?? null, props.literals, props.placeholders, true);
+    },
+    toString(props, locale) {
+        return locale.localize(props.id, props.count ?? null, props.literals, props.placeholders, false);
+    },
+    toJson(props) {
+        switch (serialContext!.nonSelfDescriptive) {
+            case 'skip':
+                return this;
+            case 'toMulti':
+                const multi: Record<string, string> = {};
+                for (const l of listLocaleDefs()) {
+                    const str = this.toString(props, l);
+                    if (str) {
+                        multi[l.id] = str;
+                    }
+                }
+                // tslint:disable-next-line: no-use-before-declare
+                return multiLoc(multi).toJSON();
+            default:
+                if (props.placeholders?.length || props.count !== undefined) {
+                    return {
+                        i18n: props.id,
+                        data: props.placeholders,
+                        count: props.count,
+                    };
+                    // throw new Error(`Cannot serialize smartloc instance "${this.id}" which has placeholders ("\${}" in string definition). Please use another SerializationContextOption.nonSelfDescriptive option`);
+                }
+                return `i18n/id:${props.id}`;
+        }
+    },
+
+});
+
+export const transformed = createKind<{ parent: InternalLocStr; transformer: (x: string) => string; }>({
+    name: 'TransformedLoc',
+    render(props, _) {
+        console.warn('Transformed localized string cannot be rendered as React nodes => fallback to parent rendering');
+        return <>{props.parent}</>;
+    },
+    toString(props, locale) {
+        const ret = props.parent.toString(locale);
+        return props.transformer(ret);
+    },
+    toJson(props) {
+        if (serialContext) {
+            throw new Error('Cannot serialize transformed localized strings');
+        }
+        return props.parent.toJSON();
+    },
+});
+export function singleLoc(text: string) {
+    return _singleLoc({ text });
+}
+
+const _singleLoc = createKind<{ text: string }>({
+    name: 'SingleLoc',
+    render(props) {
+        return props.text;
+    },
+    toString(props) {
+        return props.text;
+    },
+    toJson(props) {
+        return 'i18n/single:' + props.text;
+    },
+});
+
+
+export const multiLoc = createKind<Record<string, string>>({
+    name: 'MultiLoc',
+    render(props, locale) {
+        const t = this.toString(props, locale);
+        if (!t) {
+            return <></>;
+        }
+        return t;
+    },
+    toString(props, locale) {
+        return props[locale.id] ?? props[locale.code ?? ''];
+    },
+    toJson(props) {
+        const ret: Record<string, string> = {};
+        for (const [k, v] of Object.entries(props)) {
+            ret[`i18n:${k}`] = v;
+        }
+        return ret;
+    }
+});
+
+export function joinArray(separator: string | LocStr, items: (string | LocStr)[]): LocStr {
+    return _joinedArray({ items, separator });
+}
+
+const _joinedArray = createKind<{ separator: string | LocStr, items: (string | LocStr)[] }>({
+    name: 'LocStringArray',
+    render(props) {
+        const elts: any[] = [];
+        // locstrings are react-elements
+        for (let i = 0; i < props.items.length; i++) {
+            if (i) {
+                elts.push(props.separator);
+            }
+            elts.push(props.items[i]);
+        }
+        return asFragment(elts);
+    },
+    toString(props, locale) {
+        const sep = typeof props.separator === 'string' ? props.separator : props.separator.toString(locale);
+        return props.items.map(item => item.toString(locale)).join(sep);
+    },
+    toJson() {
+        throw new Error('Cannot transform a joined array to json');
+    }
+});

package/src/core/tag.ts

@@ -0,0 +1,40 @@
+import { smartLoc } from './smartloc';
+import { LocLiteral, LocStr } from './interfaces';
+import { autoGenerateId } from './utils';
+
+
+type Templater = (literals: TemplateStringsArray, ...placeholders: LocLiteral[]) => LocStr;
+// just a signature.
+declare function _tagSig(id: string): Templater
+declare function _tagSig(literals: TemplateStringsArray, ...placeholders: LocLiteral[]): LocStr;
+type TagSignature = typeof _tagSig;
+type LocTag = TagSignature & { plural(count: number): TagSignature };
+
+
+
+
+function __loc(count: number | undefined, idOrLiterals: string | TemplateStringsArray, ...ph: LocLiteral[]): Templater | LocStr {
+    if (typeof idOrLiterals === 'string') {
+        const id = idOrLiterals;
+        return (literals: TemplateStringsArray, ...placeholders: LocLiteral[]) => {
+            return smartLoc({ id, literals, placeholders, count });
+        };
+    }
+    return smartLoc({ id: autoGenerateId(idOrLiterals), literals: idOrLiterals, placeholders: ph, count });
+}
+
+function _loc(id: string): Templater;
+function _loc(idOrLiteralsOrCount: string | TemplateStringsArray, ...ph: LocLiteral[]): LocStr;
+function _loc(idOrLiteralsOrCount: string | TemplateStringsArray, ...ph: LocLiteral[]): Templater | LocStr {
+    return __loc(undefined, idOrLiteralsOrCount, ...ph);
+}
+_loc.plural = (count: number) => {
+    function templater(id: string): Templater;
+    function templater(template: TemplateStringsArray, ...placeholders: LocLiteral[]): Templater;
+    function templater(idOrLiterals: string | TemplateStringsArray, ...ph: LocLiteral[]): Templater | LocStr {
+        return __loc(count, idOrLiterals, ...ph);
+    }
+    return templater;
+};
+
+export const loc: LocTag = _loc as any;

package/src/core/utils.tsx

@@ -0,0 +1,24 @@
+import { sha1 } from 'js-sha1';
+import React from 'react';
+
+export function autoGenerateId(str: TemplateStringsArray | string[]): string {
+    const sha = sha1(str.join('|'));
+    return 'sha1.' + sha;
+}
+
+export function getLocaleCode(locale: string) {
+    return locale && /^[a-z]+/.exec(locale.toLowerCase())?.[0] || undefined;
+}
+
+
+export function asFragment(children: React.ReactNode[]): React.ReactNode {
+    if (children.length === 1) {
+        return children[0];
+    }
+    return <React.Fragment>{children.map((x, i) => {
+        if (React.isValidElement(x) && !x.key) {
+            return <React.Fragment key={i}>{x}</React.Fragment>;
+        }
+        return x;
+    })}</React.Fragment>;
+}

package/src/express.ts

@@ -0,0 +1,93 @@
+import { withLocales, isLocStr } from '.';
+import parser from 'accept-language-parser';
+
+const supportedMethods = [
+    { key: 'json', },
+    { key: 'jsonp', },
+    { key: 'send', fn: (v: any) => isLocStr(v) ? v.toString() : v },
+];
+
+export interface SmartlocExpressOptions {
+    /**  (optional) Waits for this promise before performing a translation. This might be for instance the promise that waits all locales to be declared via addLocale() loaded */
+    waitFor?: Promise<any>;
+    /** Custom resolution (will fall back on accept-language if this function does not return anything) */
+    customLocaleResolver?: (req: any) => string | string[] | null | undefined | Promise<string | string[] | null | undefined>;
+    /** Error logger (gives a chance to log resolution errors) */
+    errorLogger?: (err: any) => void;
+}
+
+/**
+ * Express middleware that will translate calls to .send(), .json() (etc...) based on the Accept-Language request header.
+ */
+export default function (options?: SmartlocExpressOptions) {
+    const { errorLogger, customLocaleResolver, waitFor } = options ?? {};
+    let waiter: any = waitFor;
+    return function (req: any, res: any, next: any) {
+
+        let locales: string[];
+
+        function serve() {
+            waiter = null;
+            try {
+                // === resolve locales from custom resolver
+                if (!locales) {
+                    const cust = customLocaleResolver?.(req);
+                    if (typeof cust === 'string') {
+                        locales = [cust];
+                    } else if (cust instanceof Array) {
+                        locales = cust;
+                    } else if (cust) {
+                        cust.then(resCust => {
+                            if (typeof resCust === 'string') {
+                                resCust = [resCust];
+                            }
+                            locales = resCust ?? [];
+                            serve();
+                        }, e => {
+                            errorLogger?.(e);
+                            serve();
+                        })
+                        return; // defered => method will be called again later.
+                    }
+                }
+
+                // === resolve locales from headers
+                if (!locales || !locales.length) {
+                    const lh = req?.headers?.['accept-language'];
+                    if (!lh) {
+                        next();
+                        return; // => no locale... just serve without patching
+                    }
+                    locales = parser.parse(lh)
+                        ?.map(x => x.region ? `${x.code}-${x.region}` : x.code);
+                }
+
+                // === override methods that sends potentially translatable content
+                for (const { key, fn } of supportedMethods) {
+                    const orig: Function = res[key];
+                    res[key] = function (fst: any, ...args: any[]) {
+                        return withLocales(locales, () => {
+                            return orig.call(this
+                                , fn ? fn(fst) : fst
+                                , ...args);
+                        })
+                    };
+                }
+                next();
+                return;
+            } catch (e) {
+                errorLogger?.(e);
+                next();
+            }
+        };
+
+
+        // === serve if nothing to wait
+        if (!waiter) {
+            serve();
+        } else {
+            waiter.then(serve, serve);
+        }
+
+    }
+}