import {Injectable} from "../../di" import {ErrorWithContext} from "../../util" import * as pluralize from "pluralize" import {AppClass} from "../../lifecycle/AppClass"; import {Config} from "../../service/Config"; /** * Type name for the standalone localization helper function that can be passed around * in lieu of the Locale service. */ export type LocaleHelper = (phrase: string, { plural, fallback, interp }: {plural?: number, fallback?: string, interp?: {[key: string]: any}}) => string /** * Request-level service that provides localization of phrases based on config files. */ @Injectable() export class Locale extends AppClass { protected get config() { // For some reason, was having issues with this not injecting properly. // TODO convert this back to @Inject() and solve that bug return this.app().make(Config) } constructor( /** * The preferred locale. This corresponds to the config prefix. * @example en_US means "lang:en_US" config scope * @example es_MX means "lang:es_MX" config scope */ protected locale?: string ) { super() if ( !this.locale ) { this.locale = this.getDefaultLocale() } } /** * Get the default locale that should be assigned if none is specified in the session. * @return string */ getDefaultLocale() { return this.config.get('locale.default', 'en_US') } /** * Set the preferred locale for lookups by this service. * @param locale */ setLocale(locale: string) { this.locale = locale } /** * Get a wrapped helper function that can be passed around instead of this service. */ helper(): LocaleHelper { return (phrase: string, { plural, fallback, interp }: {plural?: number, fallback?: string, interp?: {[key: string]: any}} = {}) => { return this.get(phrase, {plural, fallback, interp}) } } /** * Resolve the given phrase to the locale of this service. This is where all the magic happens. * * This method tries to load the given phrase from the config using `load()` then localizes it * using the specified parameters. * * @example * The pluralization can be specified using the `plural` parameter. If an explicit pluralization * is specified in the phrase config, that will be used. Otherwise, the `pluralize` library is * used to generate one automatically. * * ```typescript * // Example phrase config: * { * apple: 'Apple', * bunch_of_bananas: { * one: 'Bunch of Bananas', * many: 'Bunches of Bananas', * } * } * * // Example usage: * locale.get('apple', { plural: 3 }) // => 'Apples' * locale.get('apple') // => 'Apple' * locale.get('bunch_of_bananas', { plural: 2 }) // => 'Bunches of Bananas' * locale.get('bunch_of_bananas', { plural: 1}) // => 'Bunch of Bananas' * ``` * * @example * If a translation cannot be found, and a fallback is specified, the fallback will be returned. * Otherwise, the value of `phrase` is returned instead. * * ```typescript * locale.get('nonexistent_phrase', { fallback: 'Hello, world!' }) // => 'Hello, world!' * ``` * * @example * Values can be interpolated into phrases using the `interp` parameter. For example, if there is * a phrase `my_phrase: 'Hello, :name:!`, the value of `:name:` can be replaced like so: * * ```typescript * locale.get('my_phrase', {interp: {name: 'John Doe'}}) // => 'Hello, John Doe!' * ``` * * @example * If a phrase cannot be found in the specific locale config, the service will try to load it from * the equivalent `common` locale config. For example, if `this.locale` is `es_MX`: * * ```typescript * // Example "lang:common:dashboard" config: * { * title: "MyDash2.0", * header: "Welcome to the dashboard!", * } * * // Example "lang:es_MX:dashboard" config: * { * header: "¡Bienvenido al panel de control!", * } * * // Example usage: * locale.get('dashboard.title') // => 'MyDash2.0' * locale.get('dashboard.header') // => '¡Bienvenido al panel de control!' * ``` * * @param phrase * @param plural * @param fallback * @param interp */ get(phrase: string, { plural, fallback, interp }: {plural?: number, fallback?: string, interp?: {[key: string]: any}} = {}): string { const scope = phrase.split(':').reverse().slice(1).reverse().join(':') const specific = phrase.split(':').reverse()[0] const load = `${this.locale}${scope ? ':' + scope : ''}.${specific}` const translated = this.load(load) const is_plural = plural && plural !== 1 if ( !translated ) { return fallback ?? specific } let ret = '' if ( typeof translated === 'object' ) { if ( is_plural && translated.many ) { ret = translated.many } else if ( is_plural && translated.one ) { ret = pluralize(translated.one, plural) } else if ( !is_plural && translated.one ) { ret = translated.one } else if ( !is_plural && translated.many ) { ret = pluralize(translated.many, 1) } else { throw new ErrorWithContext(`Invalid translation config for ${phrase}. Must provide 'one' or 'many' keys.`, { locale: this.locale, phrase, plural, fallback, translated, }) } } else if ( typeof translated === 'string' ) { ret = pluralize(translated, is_plural ? 5 : 1) } else { throw new ErrorWithContext(`Invalid translation object for ${phrase}.`, { locale: this.locale, phrase, plural, fallback, translated, }) } if ( interp ) { for ( const key in interp ) { const rex = new RegExp(`:${key}:`, 'g') ret = ret.replace(rex, interp[key]) } } return ret } /** * Attempt to load the given locale string, merging in the appropriate common locale values. * @param locale * @protected */ protected load(locale: string) { const subloc = locale.split(':').slice(1).join(':') const specific_loc = locale.split(':').reverse()[0].split('.').slice(1).join('.') let common: any = this.config.get(`lang:common${subloc ? ':' + subloc : ''}${specific_loc ? '.' + specific_loc : ''}`, undefined) let specific: any = this.config.get(`lang:${locale}`, undefined) if ( typeof specific === 'string' ) return specific if ( typeof common === 'string' && typeof specific === 'undefined' ) return common if ( !common ) common = {} if ( !specific ) specific = {} return {...common, ...specific} } }