npm - @shoelace-style/localize - Versions diffs - 2.1.3 → 3.0.0 - Mend

@shoelace-style/localize 2.1.3 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,19 @@
 # Changelog
+## 3.0.0
+- 🚨BREAKING: Removed top level `term()`, `date()`, `number()`, and `relativeTime()` functions
+- Refactored `LocalizeController.term()` to allow strong typings by extending the controller and default translation (see "Typed Translations and Arguments" in the readme for details)
+## 2.2.1
+- Fixed a bug that prevented updates from happening when `<html dir>` changed
+## 2.2.0
+- Added `dir()` method to return the target element's directionality
+- Added `lang()` method to return the target element's language
 ## 2.1.3
 - Renamed `updateLocalizedTerms()` to `update()` (forgive me SemVer, but nobody was using this I promise)

package/README.md CHANGED Viewed

@@ -1,8 +1,8 @@
 # Shoelace: Localize
-This zero-dependency micro library does not aim to replicate a full-blown localization tool. For that, you should use something like [i18next](https://www.i18next.com/). What this library _does_ do is provide a lightweight, framework-agnostic mechanism for sharing and applying translations across one or more custom elements in a component library.
+This zero-dependency micro library does not aim to replicate a full-blown localization tool. For that, you should use something like [i18next](https://www.i18next.com/). What this library _does_ do is provide a lightweight, [Reactive Controller](https://lit.dev/docs/composition/controllers/) for sharing and applying translations across one or more custom elements in a component library.
-Included are methods for translating terms, dates, currencies, and numbers and a [Reactive Controller](https://lit.dev/docs/composition/controllers/) that can be used as a mixin in Lit and other supportive component authoring libraries.
+Reactive Controllers are supported by Lit 2 out of the box, but they're designed to be generic so other libraries can elect to support them either natively or through an adapter. If you're favorite custom element authoring library doesn't support Reactive Controllers yet, consider asking the maintainers to add support for them!
 ## Overview
@@ -11,7 +11,7 @@ Here's an example of how this library can be used to create a localized custom e
 ```ts
 import { LocalizeController, registerTranslation } from '@shoelace-style/localize';
-// Translations can also be loaded outside of the component and/or on the fly using dynamic imports
+// Note: translations can also be lazy loaded (see "Registering Translations" below)
 import en from '../translations/en';
 import es from '../translations/es';
@@ -46,9 +46,10 @@ Changes to `<html lang>` will trigger an update to all localized components auto
 It's not uncommon for a custom element to require localization, but implementing it at the component level is challenging. For example, how should we provide a translation for this close button that exists in a custom element's shadow root?
 ```html
-<button type="button" aria-label="Close">
-  <svg>...</svg>
-</button>
+#shadow-root
+  <button type="button" aria-label="Close">
+    <svg>...</svg>
+  </button>
 ```
 Typically, custom element authors dance around the problem by exposing attributes or properties for such purposes.
@@ -81,6 +82,8 @@ This library provides a set of tools to localize dates, currencies, numbers, and
 By design, `lang` attributes on ancestor elements are ignored. This is for performance reasons, as there isn't an efficient way to detect the "current language" of an arbitrary element. I consider this a gap in the platform and [I've proposed properties](https://github.com/whatwg/html/issues/7039) to make this lookup less expensive.
+Fortunately, the majority of use cases appear to favor a single language per page. However, multiple languages per page are also supported, but you'll need to explicitly set the `lang` attribute on all components whose language differs from the one set in `<html lang>`.
 ## Usage
 First, install the library.
@@ -112,10 +115,10 @@ const translation: Translation = {
   upload: 'Upload',
   // Terms with placeholders
-  greet_user: (name: string) => `Hello, ${name}!`,
+  greetUser: (name: string) => `Hello, ${name}!`,
   // Plurals
-  num_files_selected: (count: number) => {
+  numFilesSelected: (count: number) => {
     if (count === 0) return 'No files selected';
     if (count === 1) return '1 file selected';
     return `${count} files selected`;
@@ -162,7 +165,7 @@ async function changeLanguage(lang) {
 ### Localizing Components
-You can use the `LocalizeController` with any library that supports [Lit's Reactive Controller pattern](https://lit.dev/docs/composition/controllers/). In [Lit](https://lit.dev/), a localized custom element will look something like this.
+You can use the `LocalizeController` with any library that supports [Lit's Reactive Controller pattern](https://lit.dev/docs/composition/controllers/). In Lit, a localized custom element will look something like this.
 ```ts
 import { LitElement } from 'lit';
@@ -173,37 +176,66 @@ import { LocalizeController } from '@shoelace-style/localize/dist/lit.js';
 export class MyElement extends LitElement {
   private localize = new LocalizeController(this);
+  // Make sure to define `lang` so the component will respond to changes to its own lang attribute
   @property() lang: string;
   render() {
     return html`
-      <!-- Term -->
+      <!-- Terms -->
       ${this.localize.term('hello')}
-      <!-- Date -->
+      <!-- Dates -->
       ${this.localize.date('2021-09-15 14:00:00 ET'), { month: 'long', day: 'numeric', year: 'numeric' }}
-      <!-- Number/currency -->
+      <!-- Numbers/currency -->
       ${this.localize.number(1000, { style: 'currency', currency: 'USD'})}
+      <!-- Determining language -->
+      ${this.localize.lang()}
+      <!-- Determining directionality, e.g. 'ltr' or 'rtl' -->
+      ${this.localize.dir()}
     `;
   }
 }
 ```
+## Typed Translations and Arguments
+Because translations are defined by the user, there's no way for TypeScript to automatically know about the terms you've defined. This means you won't get strongly typed arguments when calling `this.localize.term()`. However, you can solve this by extending `Translation` and `LocalizeController`.
+In a separate file, e.g. `my-localize.ts`, add the following code.
+```ts
+import { LocalizeController as DefaultLocalizeController } from '@shoelace-style/localize';
+// Extend the default controller with your custom translation
+export class LocalizeController extends DefaultLocalizeController<MyTranslation> {}
+// Export `registerTranslation` so you can import everything from this file
+export { registerTranslation } from '@shoelace-style/localize';
+// Define your translation terms here
+export interface MyTranslation extends Translation {
+  myTerm: string;
+  myOtherTerm: string;
+  myTermWithArgs: (count: string) => string;
+}
+```
+Now you can import `MyLocalizeController` and get strongly typed translations when you use `this.localize.term()`!
 ## Advantages
+- Zero dependencies
 - Extremely lightweight
-  - Zero dependencies
-	- Version 2.1 measures 726 bytes (yes, _bytes_) after minify + gzip
-- Uses existing platform features
 - Supports simple terms, plurals, and complex translations
-	- Fun fact: some languages have [six plural forms](https://lingohub.com/blog/2019/02/pluralization) and this will support that
-- Supports dates, numbers, and currencies
+	- Fun fact: some languages have [six plural forms](https://lingohub.com/blog/2019/02/pluralization) and this utility supports that
+- Supports dates, numbers, and currencies using built-in [`Intl` APIs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl)
 - Good DX for custom element authors and consumers
   - Intuitive API for custom element authors
   - Consumers only need to load the translations they want and set the `lang` attribute
 - Translations can be loaded up front or on demand
-- Translations can be created by consumers without having to wait for them to get accepted upstream
 ## Disadvantages

package/dist/index.d.ts CHANGED Viewed

@@ -4,20 +4,20 @@ export interface Translation {
     $code: string;
     $name: string;
     $dir: 'ltr' | 'rtl';
+}
+export interface DefaultTranslation extends Translation {
     [key: string]: any;
 }
 export declare function registerTranslation(...translation: Translation[]): void;
-export declare function term<K extends keyof Translation>(lang: string, key: K, ...args: FunctionParams<Translation[K]>): any;
-export declare function date(lang: string, dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions): string;
-export declare function number(lang: string, numberToFormat: number | string, options?: Intl.NumberFormatOptions): string;
-export declare function relativeTime(lang: string, value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions): string;
 export declare function update(): void;
-export declare class LocalizeController implements ReactiveController {
+export declare class LocalizeController<UserTranslation extends Translation = DefaultTranslation> implements ReactiveController {
     host: ReactiveControllerHost & HTMLElement;
     constructor(host: ReactiveControllerHost & HTMLElement);
     hostConnected(): void;
     hostDisconnected(): void;
-    term<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>): any;
+    dir(): string;
+    lang(): string;
+    term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>): any;
     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 CHANGED Viewed

@@ -1,58 +1,30 @@
 const connectedElements = new Set();
 const documentElementObserver = new MutationObserver(update);
 const translations = new Map();
+let documentDirection = document.documentElement.dir || 'ltr';
 let documentLanguage = document.documentElement.lang || navigator.language;
 let fallback;
 documentElementObserver.observe(document.documentElement, {
     attributes: true,
-    attributeFilter: ['lang']
+    attributeFilter: ['dir', 'lang']
 });
 export function registerTranslation(...translation) {
     translation.map(t => {
         const code = t.$code.toLowerCase();
-        translations.set(code, t);
+        if (translations.has(code)) {
+            translations.set(code, Object.assign(Object.assign({}, translations.get(code)), t));
+        }
+        else {
+            translations.set(code, t);
+        }
         if (!fallback) {
             fallback = t;
         }
     });
     update();
 }
-export function term(lang, key, ...args) {
-    const code = lang.toLowerCase().slice(0, 2);
-    const subcode = lang.length > 2 ? lang.toLowerCase() : '';
-    const primary = translations.get(subcode);
-    const secondary = translations.get(code);
-    let term;
-    if (primary && primary[key]) {
-        term = primary[key];
-    }
-    else if (secondary && secondary[key]) {
-        term = secondary[key];
-    }
-    else if (fallback && fallback[key]) {
-        term = fallback[key];
-    }
-    else {
-        console.error(`No translation found for: ${key}`);
-        return key;
-    }
-    if (typeof term === 'function') {
-        return term(...args);
-    }
-    return term;
-}
-export function date(lang, dateToFormat, options) {
-    dateToFormat = new Date(dateToFormat);
-    return new Intl.DateTimeFormat(lang, options).format(dateToFormat);
-}
-export function number(lang, numberToFormat, options) {
-    numberToFormat = Number(numberToFormat);
-    return isNaN(numberToFormat) ? '' : new Intl.NumberFormat(lang, options).format(numberToFormat);
-}
-export function relativeTime(lang, value, unit, options) {
-    return new Intl.RelativeTimeFormat(lang, options).format(value, unit);
-}
 export function update() {
+    documentDirection = document.documentElement.dir || 'ltr';
     documentLanguage = document.documentElement.lang || navigator.language;
     [...connectedElements.keys()].map((el) => {
         if (typeof el.requestUpdate === 'function') {
@@ -71,16 +43,45 @@ export class LocalizeController {
     hostDisconnected() {
         connectedElements.delete(this.host);
     }
+    dir() {
+        return `${this.host.dir || documentDirection}`.toLowerCase();
+    }
+    lang() {
+        return `${this.host.lang || documentLanguage}`.toLowerCase();
+    }
     term(key, ...args) {
-        return term(this.host.lang || documentLanguage, key, ...args);
+        const code = this.lang().toLowerCase().slice(0, 2);
+        const regionCode = this.lang().length > 2 ? this.lang().toLowerCase() : '';
+        const primary = translations.get(regionCode);
+        const secondary = translations.get(code);
+        let term;
+        if (primary && primary[key]) {
+            term = primary[key];
+        }
+        else if (secondary && secondary[key]) {
+            term = secondary[key];
+        }
+        else if (fallback && fallback[key]) {
+            term = fallback[key];
+        }
+        else {
+            console.error(`No translation found for: ${String(key)}`);
+            return key;
+        }
+        if (typeof term === 'function') {
+            return term(...args);
+        }
+        return term;
     }
     date(dateToFormat, options) {
-        return date(this.host.lang || documentLanguage, dateToFormat, options);
+        dateToFormat = new Date(dateToFormat);
+        return new Intl.DateTimeFormat(this.lang(), options).format(dateToFormat);
     }
     number(numberToFormat, options) {
-        return number(this.host.lang || documentLanguage, numberToFormat, options);
+        numberToFormat = Number(numberToFormat);
+        return isNaN(numberToFormat) ? '' : new Intl.NumberFormat(this.lang(), options).format(numberToFormat);
     }
     relativeTime(value, unit, options) {
-        return relativeTime(this.host.lang || documentLanguage, value, unit, options);
+        return new Intl.RelativeTimeFormat(this.lang(), options).format(value, unit);
     }
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@shoelace-style/localize",
-  "version": "2.1.3",
+  "version": "3.0.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 CHANGED Viewed

@@ -6,19 +6,23 @@ export interface Translation {
   $code: string; // e.g. en, en-GB
   $name: string; // e.g. English, Español
   $dir: 'ltr' | 'rtl';
+}
+export interface DefaultTranslation extends Translation {
   [key: string]: any;
 }
 const connectedElements = new Set<HTMLElement>();
 const documentElementObserver = new MutationObserver(update);
 const translations: Map<string, Translation> = new Map();
+let documentDirection = document.documentElement.dir || 'ltr';
 let documentLanguage = document.documentElement.lang || navigator.language;
 let fallback: Translation;
 // Watch for changes on <html lang>
 documentElementObserver.observe(document.documentElement, {
   attributes: true,
-  attributeFilter: ['lang']
+  attributeFilter: ['dir', 'lang']
 });
 //
@@ -27,7 +31,13 @@ documentElementObserver.observe(document.documentElement, {
 export function registerTranslation(...translation: Translation[]) {
   translation.map(t => {
     const code = t.$code.toLowerCase();
-    translations.set(code, t);
+    if (translations.has(code)) {
+      // Merge translations that share the same language code
+      translations.set(code, { ...translations.get(code), ...t });
+    } else {
+      translations.set(code, t);
+    }
     // The first translation that's registered is the fallback
     if (!fallback) {
@@ -38,68 +48,11 @@ export function registerTranslation(...translation: Translation[]) {
   update();
 }
-//
-// Translates a term using the specified locale. Looks up translations in order of language + country codes (es-PE),
-// language code (es), then the fallback translation.
-//
-export function term<K extends keyof Translation>(lang: string, key: K, ...args: FunctionParams<Translation[K]>) {
-  const code = lang.toLowerCase().slice(0, 2); // e.g. en
-  const subcode = lang.length > 2 ? lang.toLowerCase() : ''; // e.g. en-GB
-  const primary = translations.get(subcode);
-  const secondary = translations.get(code);
-  let term: any;
-  // Look for a matching term using subcode, code, then the fallback
-  if (primary && primary[key]) {
-    term = primary[key];
-  } else if (secondary && secondary[key]) {
-    term = secondary[key];
-  } else if (fallback && fallback[key]) {
-    term = fallback[key];
-  } else {
-    console.error(`No translation found for: ${key}`);
-    return key;
-  }
-  if (typeof term === 'function') {
-    return term(...args) as string;
-  }
-  return term;
-}
-//
-// Formats a date using the specified locale.
-//
-export function date(lang: string, dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions) {
-  dateToFormat = new Date(dateToFormat);
-  return new Intl.DateTimeFormat(lang, options).format(dateToFormat);
-}
-//
-// Formats a number using the specified locale.
-//
-export function number(lang: string, numberToFormat: number | string, options?: Intl.NumberFormatOptions) {
-  numberToFormat = Number(numberToFormat);
-  return isNaN(numberToFormat) ? '' : new Intl.NumberFormat(lang, options).format(numberToFormat);
-}
-//
-// Formats a relative date using the specified locale.
-//
-export function relativeTime(
-  lang: string,
-  value: number,
-  unit: Intl.RelativeTimeFormatUnit,
-  options?: Intl.RelativeTimeFormatOptions
-) {
-  return new Intl.RelativeTimeFormat(lang, options).format(value, unit);
-}
 //
 // Updates all localized elements that are currently connected
 //
 export function update() {
+  documentDirection = document.documentElement.dir || 'ltr';
   documentLanguage = document.documentElement.lang || navigator.language;
   [...connectedElements.keys()].map((el: LitElement) => {
@@ -116,9 +69,10 @@ export function update() {
 //
 //  private localize = new LocalizeController(this);
 //
-// This will add the element to the set and make it respond to changes to <html lang> automatically. To make it respond
-// to changes to its own lang property, make it a property:
+// 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:
@@ -127,7 +81,9 @@ export function update() {
 //  ${this.localize.date('2021-12-03')}
 //  ${this.localize.number(1000000)}
 //
-export class LocalizeController implements ReactiveController {
+export class LocalizeController<UserTranslation extends Translation = DefaultTranslation>
+  implements ReactiveController
+{
   host: ReactiveControllerHost & HTMLElement;
   constructor(host: ReactiveControllerHost & HTMLElement) {
@@ -143,19 +99,62 @@ export class LocalizeController implements ReactiveController {
     connectedElements.delete(this.host);
   }
-  term<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>) {
-    return term(this.host.lang || documentLanguage, key, ...args);
+  /**
+   * Gets the host element's directionality as determined by the `dir` attribute. The return value is transformed to
+   * lowercase.
+   */
+  dir() {
+    return `${this.host.dir || documentDirection}`.toLowerCase();
+  }
+  /**
+   * Gets the host element's language as determined by the `lang` attribute. The return value is transformed to
+   * lowercase.
+   */
+  lang() {
+    return `${this.host.lang || documentLanguage}`.toLowerCase();
+  }
+  term<K extends keyof UserTranslation>(key: K, ...args: FunctionParams<UserTranslation[K]>) {
+    const code = this.lang().toLowerCase().slice(0, 2); // e.g. en
+    const regionCode = this.lang().length > 2 ? this.lang().toLowerCase() : ''; // e.g. en-gb
+    const primary = <UserTranslation>translations.get(regionCode);
+    const secondary = <UserTranslation>translations.get(code);
+    let term: any;
+    // Look for a matching term using regionCode, code, then the fallback
+    if (primary && primary[key]) {
+      term = primary[key];
+    } else if (secondary && secondary[key]) {
+      term = secondary[key];
+    } else if (fallback && fallback[key as keyof Translation]) {
+      term = fallback[key as keyof Translation];
+    } else {
+      console.error(`No translation found for: ${String(key)}`);
+      return key;
+    }
+    if (typeof term === 'function') {
+      return term(...args) as string;
+    }
+    return term;
   }
+  /** Outputs a localized date in the specified format. */
   date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions) {
-    return date(this.host.lang || documentLanguage, dateToFormat, options);
+    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) {
-    return number(this.host.lang || documentLanguage, numberToFormat, options);
+    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) {
-    return relativeTime(this.host.lang || documentLanguage, value, unit, options);
+    return new Intl.RelativeTimeFormat(this.lang(), options).format(value, unit);
   }
 }