@shoelace-style/localize 3.0.3 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 3.1.0
+
+- Added `exists()` method to determine if a term and/or a fallback term exists [#17](https://github.com/shoelace-style/localize/issues/17)
+
+## 3.0.4
+
+- Ensure return values of translation functions are always a string
+
 ## 3.0.3
 
 - Fixed a bug where regional locales stopped working

package/dist/index.d.ts

@@ -8,6 +8,10 @@ export interface Translation {
 export interface DefaultTranslation extends Translation {
     [key: string]: any;
 }
+export interface ExistsOptions {
+    lang: string;
+    includeFallback: boolean;
+}
 export declare function registerTranslation(...translation: Translation[]): void;
 export declare function update(): void;
 export declare class LocalizeController<UserTranslation extends Translation = DefaultTranslation> implements ReactiveController {
@@ -17,7 +21,9 @@ export declare class LocalizeController<UserTranslation extends Translation = De
     hostDisconnected(): void;
     dir(): string;
     lang(): string;
-    term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>): any;
+    private getTranslationData;
+    exists<K extends keyof UserTranslation>(key: K, options: Partial<ExistsOptions>): boolean;
+    term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>): string;
     date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions): string;
     number(numberToFormat: number | string, options?: Intl.NumberFormatOptions): string;
     relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;

package/dist/index.js

@@ -49,13 +49,28 @@ export class LocalizeController {
     lang() {
         return `${this.host.lang || documentLanguage}`.toLowerCase();
     }
-    term(key, ...args) {
+    getTranslationData(lang) {
         var _a, _b;
-        const locale = new Intl.Locale(this.lang());
+        const locale = new Intl.Locale(lang);
         const language = locale === null || locale === void 0 ? void 0 : locale.language.toLowerCase();
         const region = (_b = (_a = locale === null || locale === void 0 ? void 0 : locale.region) === null || _a === void 0 ? void 0 : _a.toLowerCase()) !== null && _b !== void 0 ? _b : '';
         const primary = translations.get(`${language}-${region}`);
         const secondary = translations.get(language);
+        return { locale, language, region, primary, secondary };
+    }
+    exists(key, options) {
+        var _a;
+        const { primary, secondary } = this.getTranslationData((_a = options.lang) !== null && _a !== void 0 ? _a : this.lang());
+        options = Object.assign({ includeFallback: false }, options);
+        if ((primary && primary[key]) ||
+            (secondary && secondary[key]) ||
+            (options.includeFallback && fallback && fallback[key])) {
+            return true;
+        }
+        return false;
+    }
+    term(key, ...args) {
+        const { primary, secondary } = this.getTranslationData(this.lang());
         let term;
         if (primary && primary[key]) {
             term = primary[key];
@@ -68,7 +83,7 @@ export class LocalizeController {
         }
         else {
             console.error(`No translation found for: ${String(key)}`);
-            return key;
+            return String(key);
         }
         if (typeof term === 'function') {
             return term(...args);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoelace-style/localize",
-  "version": "3.0.3",
+  "version": "3.1.0",
   "description": "A micro library for localizing custom elements using Lit's Reactive Controller model.",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/index.ts

@@ -12,6 +12,11 @@ export interface DefaultTranslation extends Translation {
   [key: string]: any;
 }
 
+export interface ExistsOptions {
+  lang: string;
+  includeFallback: boolean;
+}
+
 const connectedElements = new Set<HTMLElement>();
 const documentElementObserver = new MutationObserver(update);
 const translations: Map<string, Translation> = new Map();
@@ -25,9 +30,7 @@ documentElementObserver.observe(document.documentElement, {
   attributeFilter: ['dir', 'lang']
 });
 
-//
-// Registers one or more translations
-//
+/** Registers one or more translations */
 export function registerTranslation(...translation: Translation[]) {
   translation.map(t => {
     const code = t.$code.toLowerCase();
@@ -48,9 +51,7 @@ export function registerTranslation(...translation: Translation[]) {
   update();
 }
 
-//
-// Updates all localized elements that are currently connected
-//
+/** Updates all localized elements that are currently connected */
 export function update() {
   documentDirection = document.documentElement.dir || 'ltr';
   documentLanguage = document.documentElement.lang || navigator.language;
@@ -62,25 +63,25 @@ export function update() {
   });
 }
 
-//
-// Reactive controller
-//
-// To use this controller, import the class and instantiate it in a custom element constructor:
-//
-//  private localize = new LocalizeController(this);
-//
-// This will add the element to the set and make it respond to changes to <html dir|lang> automatically. To make it
-// respond to changes to its own dir|lang properties, make it a property:
-//
-//  @property() dir: string;
-//  @property() lang: string;
-//
-// To use a translation method, call it like this:
-//
-//  ${this.localize.term('term_key_here')}
-//  ${this.localize.date('2021-12-03')}
-//  ${this.localize.number(1000000)}
-//
+/**
+ * Localize Reactive Controller for components built with Lit
+ *
+ * To use this controller, import the class and instantiate it in a custom element constructor:
+ *
+ * private localize = new LocalizeController(this);
+ *
+ * This will add the element to the set and make it respond to changes to <html dir|lang> automatically. To make it
+ * respond to changes to its own dir|lang properties, make it a property:
+ *
+ *   @property() dir: string;
+ *   @property() lang: string;
+ *
+ * To use a translation method, call it like this:
+ *
+ *   ${this.localize.term('term_key_here')}
+ *   ${this.localize.date('2021-12-03')}
+ *   ${this.localize.number(1000000)}
+ */
 export class LocalizeController<UserTranslation extends Translation = DefaultTranslation>
   implements ReactiveController
 {
@@ -115,12 +116,39 @@ export class LocalizeController<UserTranslation extends Translation = DefaultTra
     return `${this.host.lang || documentLanguage}`.toLowerCase();
   }
 
-  term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>) {
-    const locale = new Intl.Locale(this.lang());
+  private getTranslationData(lang: string) {
+    const locale = new Intl.Locale(lang);
     const language = locale?.language.toLowerCase();
     const region = locale?.region?.toLowerCase() ?? '';
     const primary = <UserTranslation>translations.get(`${language}-${region}`);
     const secondary = <UserTranslation>translations.get(language);
+
+    return { locale, language, region, primary, secondary };
+  }
+
+  /** Determines if the specified term exists, optionally checking the fallback translation. */
+  exists<K extends keyof UserTranslation>(key: K, options: Partial<ExistsOptions>): boolean {
+    const { primary, secondary } = this.getTranslationData(options.lang ?? this.lang());
+
+    options = {
+      includeFallback: false,
+      ...options
+    };
+
+    if (
+      (primary && primary[key]) ||
+      (secondary && secondary[key]) ||
+      (options.includeFallback && fallback && fallback[key as keyof Translation])
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /** Outputs a translated term. */
+  term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>): string {
+    const { primary, secondary } = this.getTranslationData(this.lang());
     let term: any;
 
     // Look for a matching term using regionCode, code, then the fallback
@@ -132,7 +160,7 @@ export class LocalizeController<UserTranslation extends Translation = DefaultTra
       term = fallback[key as keyof Translation];
     } else {
       console.error(`No translation found for: ${String(key)}`);
-      return key;
+      return String(key);
     }
 
     if (typeof term === 'function') {
@@ -143,19 +171,19 @@ export class LocalizeController<UserTranslation extends Translation = DefaultTra
   }
 
   /** Outputs a localized date in the specified format. */
-  date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions) {
+  date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions): string {
     dateToFormat = new Date(dateToFormat);
     return new Intl.DateTimeFormat(this.lang(), options).format(dateToFormat);
   }
 
   /** Outputs a localized number in the specified format. */
-  number(numberToFormat: number | string, options?: Intl.NumberFormatOptions) {
+  number(numberToFormat: number | string, options?: Intl.NumberFormatOptions): string {
     numberToFormat = Number(numberToFormat);
     return isNaN(numberToFormat) ? '' : new Intl.NumberFormat(this.lang(), options).format(numberToFormat);
   }
 
   /** Outputs a localized time in relative format. */
-  relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions) {
+  relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string {
     return new Intl.RelativeTimeFormat(this.lang(), options).format(value, unit);
   }
 }