npm - @shoelace-style/localize - Versions diffs - 1.1.6 → 2.1.0 - Mend

@shoelace-style/localize 1.1.6 → 2.1.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 (12) hide show

package/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,9 @@
+# Changelog
+## 2.1.0
+- Added relative time method to
+## 2.0.0
+- Reworked the library to use the [ReactiveController](https://lit.dev/docs/composition/controllers/) interface

package/README.md CHANGED Viewed

@@ -2,33 +2,36 @@
 This 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.
-Included are methods for translating terms, dates, currencies, and numbers, as well as corresponding directives for Lit and FAST.
+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.
 ## Overview
-Here's an example of how this library can be used to create a custom element with Lit.
+Here's an example of how this library can be used to create a localized custom element with Lit.
 ```ts
-import { registerTranslation } from '@shoelace-style/localize';
-import { localize, translate as t } from '@shoelace-style/localize/dist/lit.js';
+import { LocalizeController, registerTranslation } from '@shoelace-style/localize';
+// Translations can also be loaded outside of the component and/or on the fly using dynamic imports
 import en from '../translations/en';
 import es from '../translations/es';
-registerTranslation(en, es); // Translations can also be loaded outside of the component and/or on demand
+registerTranslation(en, es);
 @customElement('my-element')
-@localize()
 export class MyElement extends LitElement {
+  private localize = new LocalizeController(this);
+  @property() lang: string;
   render() {
     return html`
-      <h1>${t('hello_user', 'world')}</h1>  <!-- outputs "Hello, world!" -->
+      <h1>${this.localize.term('hello_world')}</h1>
     `;
   }
 }
 ```
-Here's how your consumers will change languages.
+To set the page locale, apply the desired `lang` attribute to the `<html>` element.
 ```html
 <html lang="es">
@@ -36,7 +39,7 @@ Here's how your consumers will change languages.
 </html>
 ```
-Simply changing the `lang` attribute on any element in the DOM will trigger an update to all localized components.
+Changes to `<html lang>` will trigger an update to all localized components automatically.
 ## Why this instead of an i18n library?
@@ -44,7 +47,7 @@ It's not uncommon for a custom element to require localization, but implementing
 ```html
 <button type="button" aria-label="Close">
-  <svg><!-- close icon --></svg>
+  <svg>...</svg>
 </button>
 ```
@@ -58,39 +61,25 @@ Typically, custom element authors dance around the problem by exposing attribute
 But this approach offloads the problem to the user so they have to provide every term, every time. It also doesn't scale with more complex components that have more than a handful of terms to be translated.
-This is the use case this library is solving for. It is by no means intended to solve localization at the framework level. There are much better tools for that.
+This is the use case this library is solving for. It is not intended to solve localization at the framework level. There are much better tools for that.
 ## How it works
-To achieve this goal, we lean on HTML’s [`lang`](~https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang~) attribute to determine what languages should be used in various parts of the page. The default language is specified by `<html lang>`, but any element in the DOM can be scoped to a language by setting its `lang` attribute. This means you can have more than one language per page, if desired.
+To achieve this goal, we lean on HTML’s [`lang`](~https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang~) attribute to determine what language should be used. The default locale is specified by `<html lang="...">`, but any localized element can be scoped to a locale by setting its `lang` attribute. This means you can have more than one language per page, if desired.
 ```html
 <html lang="en">
 <body>
   <my-element>This element will be English</my-element>
-  <div lang="es">
-    <my-element>This element will be Spanish</my-element>
-    <my-element>This element is also Spanish</my-element>
-  </div>
+  <my-element lang="es">This element will be Spanish</my-element>
+  <my-element lang="fr">This element will be French</my-element>
 </body>
 </html>
 ```
-This library provides a set of tools to localize dates, currencies, numbers, and terms in your custom element library with a minimal footprint. Reactivity is achieved with a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) that listens for `lang` changes in the document. This means that changing a `lang` attribute in the DOM will automatically update all localized elements.
+This library provides a set of tools to localize dates, currencies, numbers, and terms in your custom element library with a minimal footprint. Reactivity is achieved with a [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) that listens for `lang` changes on `<html>`.
-_Exception: The mutation observer will not track `lang` changes within shadow roots. For this, there is a `forceUpdate()` method you can call to tell localized elements to update._
-When a localized element is connected to the DOM, the library looks for the closest `lang` attribute, moving up through its ancestors and breaking through shadow roots as necessary. The element and its language are then cached internally. When a `lang` attribute changes. the library loops through all connected components, re-detects their language, and tells them to update. When an element is disconnected from the DOM, it is discarded from the map.
-By caching languages in a map, we're able to limit expensive DOM traversal so it only occurs:
-1. When the element is connected
-2. When a `lang` attribute changes
-At this time, there is no easier 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 more efficient.
+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.
 ## Usage
@@ -102,13 +91,13 @@ npm install @shoelace-style/localize
 Next, follow these steps to localize your components.
-1. Create one or more translations
-2. Register the translations
+1. Create a translation
+2. Register the translation
 3. Localize your components
-### Creating Translations
+### Creating a Translation
-Every translation must extend the `Translation` type. All translations must implement the required meta properties (denoted by a `$` prefix) and additional terms can be implemented as show below.
+All translations must extend the `Translation` type and implement the required meta properties (denoted by a `$` prefix). Additional terms can be implemented as show below.
 ```ts
 // en.ts
@@ -119,11 +108,11 @@ const translation: Translation = {
   $name: 'English',
   $dir: 'ltr',
-  // Terms
+  // Simple terms
   upload: 'Upload',
-  // Placeholders
-  hello_user: (name: string) => `Hello, ${name}!`,
+  // Terms with placeholders
+  greet_user: (name: string) => `Hello, ${name}!`,
   // Plurals
   num_files_selected: (count: number) => {
@@ -148,13 +137,15 @@ import es from './es';
 registerTranslation(en, es);
 ```
-The first translation to be registered will be used as the "fallback". That is, if a term is missing from the target language, the fallback language will be used instead.
+The first translation that's registered will be used as the _fallback_. That is, if a term is missing from the target language, the fallback language will be used instead.
+Translations registered with country such as `en-GB` are supported. However, your fallback translation must be registered with only a language code (e.g. `en`) to ensure users of unsupported regions will still receive a comprehensible translation.
-Translations registered with subcodes such as `en-GB` are supported. However, your fallback translation must be registered with a base code (e.g. `en`) to ensure users of unsupported regions will still receive a comprehensible translation.
+For example, if you're fallback language is `en-US`, you should register it as `en` so users with unsupported `en-*` country codes will receive it as a fallback. Then you can register country codes such as `en-GB` and `en-AU` to improve the experience for additional regions.
-For example, if you're fallback language is `en-US`, you should register it as `en` so users with unsupported `en-*` subcodes will receive it as a fallback. Then you can register subcodes such as `en-GB` and `en-AU` to improve the experience for those additional regions.
+It's important to note that translations _do not_ have to be registered up front. You can register them on demand as the language changes in your app. Upon registration, localized components will update automatically.
-It's important to note that translations _do not_ have to be registered up front. You can register them on demand as the language changes in your app. Upon import, all localized components will update automatically.
+Here's a sample function that dynamically loads a translation.
 ```ts
 import { registerTranslation } from '@shoelace-style/localize';
@@ -169,177 +160,51 @@ async function changeLanguage(lang) {
 }
 ```
-### Lit
+### Localizing Components
-If you're using [Lit](https://lit.dev/) to develop 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.
 ```ts
 import { LitElement } from 'lit';
 import { customElement } from 'lit/decorators.js';
-import { localize, translate as t, formatDate as d, formatNumber as n } from '@shoelace-style/localize/dist/lit.js';
+import { LocalizeController } from '@shoelace-style/localize/dist/lit.js';
 @customElement('my-element')
-@localize()
 export class MyElement extends LitElement {
+  private localize = new LocalizeController(this);
+  @property() lang: string;
   render() {
     return html`
       <!-- Term -->
-      ${t('hello')}
+      ${this.localize.term('hello')}
       <!-- Date -->
-      ${d('2021-09-15 14:00:00 ET'), { month: 'long', day: 'numeric', year: 'numeric' }}
+      ${this.localize.date('2021-09-15 14:00:00 ET'), { month: 'long', day: 'numeric', year: 'numeric' }}
-      <!-- Currency -->
-      ${n(1000, { style: 'currency', currency: 'USD'})}
+      <!-- Number/currency -->
+      ${this.localize.number(1000, { style: 'currency', currency: 'USD'})}
     `;
   }
 }
 ```
-### FAST
-If you're using [FAST Element](https://www.fast.design/) to develop components:
-```ts
-import { FASTElement, customElement } from '@microsoft/fast-element';
-import { localize, translate as t, formatDate as d, formatNumber as n } from '@shoelace-style/localize/dist/lit.js';
-const template = html<MyElement>`
-  <!-- Term -->
-  ${x => t(x, 'hello')}
-  <!-- Date -->
-  ${x => d(x, '2021-09-15 14:00:00 ET'), { month: 'long', day: 'numeric', year: 'numeric' }}
-  <!-- Currency -->
-  ${x => n(x, 1000, { style: 'currency', currency: 'USD'})}
-`;
-@customElement({
-  name: 'my-element',
-  template
-})
-export class MyElement extends FASTElement {
-  // ...
-}
-```
-**Note:** This directive requires a context to be passed as the first argument. This is required because of a limitation in FAST's rendering engine that causes inconsistencies when a directive is used as `${t('example')}` vs. `${x => t('example')}`.
-### No Library (Advanced)
-To use this without a custom element library, you'll need to follow this pattern.
-```ts
-import { connectedElements, detectLanguage, forceUpdate } from '@shoelace-style/localize';
-class MyElement extends HTMLElement {
-  connectedCallback() {
-    // Register the component when it's connected and cache the current language
-    const lang = detectLanguage(this);
-    connectedElements.set(this, lang);
-  }
-  disconnectedCallback() {
-    // Remove the element from cache when it disconnects from the DOM
-    connectedElements.delete(this);
-  }
-  updateLocalizedTerms() {
-    // Called when the lang changes (this is where you update all localized terms in the element)
-  }
-  static get observedAttributes() {
-    return ['lang'];
-  }
-  attributeChangedCallback(name, oldValue, newValue) {
-    // When lang changes, update the cache and trigger an update
-    if (name === 'lang') {
-      this.updateLocalizedTerms();
-    }
-  }
-}
-```
-Three core translation functions are exposed for translating terms, dates, numbers, and currencies. The `translate()` function relies on the translations you provide, while the `formatDate()` and `formatNumber()` functions use the [`Intl` API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) to localize dates, numbers, and currencies.
-These are the functions that get called internally by the Lit directives. Note that `lang` is a required argument. If you use this API, make sure to use the cached language values available in the `connectedElements` map to avoid expensive DOM traversal.
-```ts
-function translate(lang: string, key: string, args: any) {
-  // returns a localized term
-}
-function formatDate(lang: string, date: Date | string, options: Intl.DateTimeFormatOptions) {
-  // returns a localized date
-}
-function formatNumber(lang: string, number: number | string, options?: Intl.NumberFormatOptions) {
-  // returns a localized number or currency
-}
-```
-### Typed Arguments
-As the `Translation` interface is extended by the user, and because terms can have varying arguments, there's no way for TypeScript to automatically know about the terms you've added. This means we won't get strongly typed arguments when calling `translate()` or a translate directive.
-However, you can optionally extend the `Translation` interface with your own and wrap the translation functions you want to enable strong typings for.
-```ts
-// translation.ts
-import type { FunctionParams, Translation as BaseTranslation } from '@shoelace-style/localize';
-import { translate as internalTranslate } from '@shoelace-style/localize';
-import { translate as litTranslate } from '@shoelace-style/localize/dist/lit.js';
-export interface Translation extends BaseTranslation {
-  upload: string;
-  hello_user: (name: string) => string;
-  num_files_selected: (count: number) => string;
-}
-// Wrap the translate function
-export function translate<T extends keyof Translation>(lang: string, key: T, ...args: FunctionParams<Translation[T]>) {
-  return internalTranslate(lang, key, ...args) as unknown;
-}
-// Wrap the Lit translate directive
-export function translateDirective<T extends keyof Translation>(key: T, ...args: FunctionParams<Translation[T]>) {
-  return litTranslate(key, ...args) as unknown;
-}
-```
-Now, instead of importing from `@shoelace-style/localize`, you can import these functions from your own `translation.ts` module and you'll get strongly typed translation keys and arguments!
-### Appending Terms
-Occassionaly, third-party components may want to make use of your localization library. Should you choose to expose this as an option, here's how terms can be added to translations that are already registered.
-```ts
-import en from './en';
-en.logout = 'Logout';
-en.goodbye_user = (name: string) => `Goodbye, ${name}`;
-```
 ## Advantages
 - Extremely lightweight
-	- ~2.7 KB compared to ~33 KB for i18next (both without translations; both minified, not gzipped)
+	- ~2.5 KB compared to ~33 KB for i18next (both without translations/minifications)
 - 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
 - Good DX for custom element authors and consumers
-	- Authors have directives to localize components using popular libraries
-	- Consumers only need to load the translations they want to use and set the `lang` attribute
+  - 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
-- Strong typings when using translations (requires a custom Translation interface and a wrapper function)
 ## Disadvantages
 - Complex translations require some code, such as conditionals
 	- This is arguably no more difficult than, for example, adding them to a [YAML](https://edgeguides.rubyonrails.org/i18n.html#pluralization) or [XLIFF](https://en.wikipedia.org/wiki/XLIFF) file
-Note that we aren’t aiming to solve localization at the framework level. Many teams already have their own translation libraries, so we need to provide something that will work in tandem with those with a minimal learning curve.

package/dist/index.d.ts CHANGED Viewed

@@ -1,3 +1,4 @@
+import { ReactiveController, ReactiveControllerHost } from 'lit';
 export declare type FunctionParams<T> = T extends (...args: infer U) => string ? U : never;
 export interface Translation {
     $code: string;
@@ -5,10 +6,19 @@ export interface Translation {
     $dir: 'ltr' | 'rtl';
     [key: string]: any;
 }
-export declare const connectedElements: Map<HTMLElement, string>;
-export declare function detectLanguage(el: HTMLElement): string;
 export declare function registerTranslation(...translation: Translation[]): void;
-export declare function translate<K extends keyof Translation>(lang: string, key: K, ...args: FunctionParams<Translation[K]>): any;
-export declare function formatDate(lang: string, date: Date | string, options?: Intl.DateTimeFormatOptions): string;
-export declare function formatNumber(lang: string, number: number | string, options?: Intl.NumberFormatOptions): string;
-export declare function forceUpdate(): 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 updateLocalizedTerms(): void;
+export declare class LocalizeController 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;
+    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,20 +1,12 @@
-export const connectedElements = new Map();
-const documentElementObserver = new MutationObserver(() => forceUpdate());
+const connectedElements = new Set();
+const documentElementObserver = new MutationObserver(updateLocalizedTerms);
 const translations = new Map();
+let documentLanguage = document.documentElement.lang || navigator.language;
 let fallback;
-function closest(selector, root = this) {
-    function getNext(el, next = el && el.closest(selector)) {
-        if (el instanceof Window || el instanceof Document || !el) {
-            return null;
-        }
-        return next ? next : getNext(el.getRootNode().host);
-    }
-    return getNext(root);
-}
-export function detectLanguage(el) {
-    const closestEl = closest('[lang]', el);
-    return closestEl === null || closestEl === void 0 ? void 0 : closestEl.lang;
-}
+documentElementObserver.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ['lang']
+});
 export function registerTranslation(...translation) {
     translation.map(t => {
         const code = t.$code.toLowerCase();
@@ -23,8 +15,9 @@ export function registerTranslation(...translation) {
             fallback = t;
         }
     });
+    updateLocalizedTerms();
 }
-export function translate(lang, key, ...args) {
+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);
@@ -40,7 +33,7 @@ export function translate(lang, key, ...args) {
         term = fallback[key];
     }
     else {
-        console.error(`Cannot find "${key}" to translate.`);
+        console.error(`No translation found for: ${key}`);
         return key;
     }
     if (typeof term === 'function') {
@@ -48,26 +41,46 @@ export function translate(lang, key, ...args) {
     }
     return term;
 }
-export function formatDate(lang, date, options) {
-    date = new Date(date);
-    return new Intl.DateTimeFormat(lang, options).format(date);
+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 formatNumber(lang, number, options) {
-    number = Number(number);
-    return isNaN(number) ? '' : new Intl.NumberFormat(lang, options).format(number);
+export function relativeTime(lang, value, unit, options) {
+    return new Intl.RelativeTimeFormat(lang, options).format(value, unit);
 }
-export function forceUpdate() {
-    [...connectedElements.keys()].map(el => {
-        const lang = detectLanguage(el);
-        connectedElements.set(el, lang);
-        if (typeof el.updateLocalizedTerms === 'function') {
-            el.updateLocalizedTerms();
+export function updateLocalizedTerms() {
+    documentLanguage = document.documentElement.lang || navigator.language;
+    [...connectedElements.keys()].map((el) => {
+        if (typeof el.requestUpdate === 'function') {
+            el.requestUpdate();
         }
     });
 }
-documentElementObserver.observe(document.documentElement, {
-    attributes: true,
-    attributeFilter: ['lang'],
-    childList: true,
-    subtree: true
-});
+export class LocalizeController {
+    constructor(host) {
+        this.host = host;
+        this.host.addController(this);
+    }
+    hostConnected() {
+        connectedElements.add(this.host);
+    }
+    hostDisconnected() {
+        connectedElements.delete(this.host);
+    }
+    term(key, ...args) {
+        return term(this.host.lang || documentLanguage, key, ...args);
+    }
+    date(dateToFormat, options) {
+        return date(this.host.lang || documentLanguage, dateToFormat, options);
+    }
+    number(numberToFormat, options) {
+        return number(this.host.lang || documentLanguage, numberToFormat, options);
+    }
+    relativeTime(value, unit, options) {
+        return relativeTime(this.host.lang || documentLanguage, value, unit, options);
+    }
+}

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@shoelace-style/localize",
-  "version": "1.1.6",
-  "description": "A micro library for localizing custom elements.",
+  "version": "2.1.0",
+  "description": "A micro library for localizing custom elements using Lit's Reactive Controller model.",
   "main": "/dist/index.js",
   "module": "/dist/index.js",
   "type": "module",
@@ -37,7 +37,6 @@
     "typescript": "^4.4.3"
   },
   "dependencies": {
-    "@microsoft/fast-element": "^1.5.1",
-    "lit": "*"
+    "lit": "^2.0.2"
   }
 }

package/src/index.ts CHANGED Viewed

@@ -1,53 +1,53 @@
+import { LitElement, ReactiveController, ReactiveControllerHost } from 'lit';
 export type FunctionParams<T> = T extends (...args: infer U) => string ? U : never;
 export interface Translation {
   $code: string; // e.g. en, en-GB
   $name: string; // e.g. English, Español
   $dir: 'ltr' | 'rtl';
   [key: string]: any;
 }
-export const connectedElements = new Map<HTMLElement, string>();
-const documentElementObserver = new MutationObserver(() => forceUpdate());
+const connectedElements = new Set<HTMLElement>();
+const documentElementObserver = new MutationObserver(updateLocalizedTerms);
 const translations: Map<string, Translation> = new Map();
+let documentLanguage = document.documentElement.lang || navigator.language;
 let fallback: Translation;
-function closest(selector: string, root: Element = this) {
-  function getNext(el: Element | HTMLElement, next = el && el.closest(selector)): Element | null {
-    if (el instanceof Window || el instanceof Document || !el) {
-      return null;
-    }
-    return next ? next : getNext((el.getRootNode() as ShadowRoot).host);
-  }
-  return getNext(root);
-}
-export function detectLanguage(el: HTMLElement) {
-  const closestEl = closest('[lang]', el) as HTMLElement;
-  return closestEl?.lang;
-}
+// Watch for changes on <html lang>
+documentElementObserver.observe(document.documentElement, {
+  attributes: true,
+  attributeFilter: ['lang']
+});
+//
+// Registers one or more translations
+//
 export function registerTranslation(...translation: Translation[]) {
   translation.map(t => {
     const code = t.$code.toLowerCase();
     translations.set(code, t);
-    // Use the first translation that's registered as the fallback
+    // The first translation that's registered is the fallback
     if (!fallback) {
       fallback = t;
     }
   });
+  updateLocalizedTerms();
 }
-export function translate<K extends keyof Translation>(lang: string, key: K, ...args: FunctionParams<Translation[K]>) {
+//
+// 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-US
+  const subcode = lang.length > 2 ? lang.toLowerCase() : ''; // e.g. en-GB
   const primary = translations.get(subcode);
   const secondary = translations.get(code);
-  let term;
+  let term: any;
   // Look for a matching term using subcode, code, then the fallback
   if (primary && primary[key]) {
@@ -57,42 +57,105 @@ export function translate<K extends keyof Translation>(lang: string, key: K, ...
   } else if (fallback && fallback[key]) {
     term = fallback[key];
   } else {
-    console.error(`Cannot find "${key}" to translate.`);
+    console.error(`No translation found for: ${key}`);
     return key;
   }
   if (typeof term === 'function') {
-    return term(...args);
+    return term(...args) as string;
   }
   return term;
 }
-export function formatDate(lang: string, date: Date | string, options?: Intl.DateTimeFormatOptions) {
-  date = new Date(date);
-  return new Intl.DateTimeFormat(lang, options).format(date);
+//
+// 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);
 }
-export function formatNumber(lang: string, number: number | string, options?: Intl.NumberFormatOptions) {
-  number = Number(number);
-  return isNaN(number) ? '' : new Intl.NumberFormat(lang, options).format(number);
+//
+// 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);
 }
-export function forceUpdate() {
-  [...connectedElements.keys()].map(el => {
-    const lang = detectLanguage(el);
-    connectedElements.set(el, lang);
+//
+// Updates the locale for all localized elements that are currently connected
+//
+export function updateLocalizedTerms() {
+  documentLanguage = document.documentElement.lang || navigator.language;
-    if (typeof (el as any).updateLocalizedTerms === 'function') {
-      (el as any).updateLocalizedTerms();
+  [...connectedElements.keys()].map((el: LitElement) => {
+    if (typeof el.requestUpdate === 'function') {
+      el.requestUpdate();
     }
   });
 }
-// Update connected elements when a lang attribute changes
-documentElementObserver.observe(document.documentElement, {
-  attributes: true,
-  attributeFilter: ['lang'],
-  childList: true,
-  subtree: true
-});
+//
+// 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 lang> automatically. To make it respond
+// to changes to its own lang property, make it a property:
+//
+//  @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 implements ReactiveController {
+  host: ReactiveControllerHost & HTMLElement;
+  constructor(host: ReactiveControllerHost & HTMLElement) {
+    this.host = host;
+    this.host.addController(this);
+  }
+  hostConnected() {
+    connectedElements.add(this.host);
+  }
+  hostDisconnected() {
+    connectedElements.delete(this.host);
+  }
+  term<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>) {
+    return term(this.host.lang || documentLanguage, key, ...args);
+  }
+  date(dateToFormat: Date | string, options?: Intl.DateTimeFormatOptions) {
+    return date(this.host.lang || documentLanguage, dateToFormat, options);
+  }
+  number(numberToFormat: number | string, options?: Intl.NumberFormatOptions) {
+    return number(this.host.lang || documentLanguage, numberToFormat, options);
+  }
+  relativeTime(value: number, unit: Intl.RelativeTimeFormatUnit, options?: Intl.RelativeTimeFormatOptions) {
+    return relativeTime(this.host.lang || documentLanguage, value, unit, options);
+  }
+}

package/dist/fast.d.ts DELETED Viewed

@@ -1,6 +0,0 @@
-import type { CaptureType, ExecutionContext, FASTElement } from '@microsoft/fast-element';
-import type { FunctionParams, Translation } from './';
-export declare function localize(): (targetClass: any) => any;
-export declare function translate<TSource, K extends keyof Translation>(context: ExecutionContext | FASTElement | HTMLElement, key: K, ...args: FunctionParams<Translation[K]>): CaptureType<TSource>;
-export declare function formatDate<TSource = any>(context: ExecutionContext | FASTElement | HTMLElement, date: Date | string, options?: Intl.DateTimeFormatOptions): CaptureType<TSource>;
-export declare function formatNumber<TSource = any>(context: ExecutionContext | FASTElement | HTMLElement, number: number | string, options?: Intl.DateTimeFormatOptions): CaptureType<TSource>;

package/dist/fast.js DELETED Viewed

@@ -1,51 +0,0 @@
-import { connectedElements, detectLanguage, translate as t, formatDate as d, formatNumber as n } from './';
-export function localize() {
-    return (targetClass) => {
-        return class extends targetClass {
-            constructor() {
-                super();
-            }
-            connectedCallback() {
-                super.connectedCallback();
-                const lang = detectLanguage(this);
-                connectedElements.set(this, lang);
-            }
-            disconnectedCallback() {
-                super.disconnectedCallback();
-                connectedElements.delete(this);
-            }
-            get lang() {
-                return this.getAttribute('lang');
-            }
-            set lang(value) {
-                if (value === null || value === undefined) {
-                    this.removeAttribute('lang');
-                }
-                else {
-                    this.setAttribute('lang', value);
-                }
-                connectedElements.set(this, value);
-                this.updateLocalizedTerms();
-            }
-            updateLocalizedTerms() {
-                this.$fastController.renderTemplate(this.$fastController.template);
-            }
-        };
-    };
-}
-function getLang(source) {
-    let lang = '';
-    if (source instanceof HTMLElement) {
-        lang = connectedElements.get(source) || '';
-    }
-    return lang;
-}
-export function translate(context, key, ...args) {
-    return t(getLang(context), key, ...args);
-}
-export function formatDate(context, date, options) {
-    return d(getLang(context), date, options);
-}
-export function formatNumber(context, number, options) {
-    return n(getLang(context), number, options);
-}

package/dist/lit.d.ts DELETED Viewed

@@ -1,22 +0,0 @@
-import { Directive, Part } from 'lit/directive.js';
-import type { FunctionParams, Translation } from './';
-export declare function localize(): (targetClass: any) => any;
-declare class TranslateDirective extends Directive {
-    host: HTMLElement | undefined;
-    constructor(part: Part);
-    render<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>): any;
-}
-export declare function translate<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>): import("lit-html/directive").DirectiveResult<typeof TranslateDirective>;
-declare class FormatDateDirective extends Directive {
-    host: HTMLElement | undefined;
-    constructor(part: Part);
-    render(date: Date | string, options?: Intl.DateTimeFormatOptions): string;
-}
-export declare const formatDate: (date: string | Date, options?: Intl.DateTimeFormatOptions | undefined) => import("lit-html/directive").DirectiveResult<typeof FormatDateDirective>;
-declare class FormatNumberDirective extends Directive {
-    host: HTMLElement | undefined;
-    constructor(part: Part);
-    render(number: number | string, options?: Intl.NumberFormatOptions): string;
-}
-export declare const formatNumber: (number: string | number, options?: Intl.NumberFormatOptions | undefined) => import("lit-html/directive").DirectiveResult<typeof FormatNumberDirective>;
-export {};

package/dist/lit.js DELETED Viewed

@@ -1,62 +0,0 @@
-import { Directive, directive } from 'lit/directive.js';
-import { connectedElements, detectLanguage, formatDate as d, formatNumber as n, translate as t } from './';
-export function localize() {
-    return (targetClass) => {
-        return class extends targetClass {
-            static get properties() {
-                return Object.assign({ lang: { type: String } }, targetClass.properties);
-            }
-            connectedCallback() {
-                super.connectedCallback();
-                const lang = detectLanguage(this);
-                connectedElements.set(this, lang);
-            }
-            disconnectedCallback() {
-                super.disconnectedCallback();
-                connectedElements.delete(this);
-            }
-            updateLocalizedTerms() {
-                this.requestUpdate();
-            }
-        };
-    };
-}
-class TranslateDirective extends Directive {
-    constructor(part) {
-        var _a;
-        super(part);
-        this.host = (_a = part.options) === null || _a === void 0 ? void 0 : _a.host;
-    }
-    render(key, ...args) {
-        const lang = connectedElements.get(this.host) || '';
-        return t(lang, key, ...args);
-    }
-}
-const litDirective = directive(TranslateDirective);
-export function translate(key, ...args) {
-    return litDirective(key, ...args);
-}
-class FormatDateDirective extends Directive {
-    constructor(part) {
-        var _a;
-        super(part);
-        this.host = (_a = part.options) === null || _a === void 0 ? void 0 : _a.host;
-    }
-    render(date, options) {
-        const lang = connectedElements.get(this.host) || '';
-        return d(lang, date, options);
-    }
-}
-export const formatDate = directive(FormatDateDirective);
-class FormatNumberDirective extends Directive {
-    constructor(part) {
-        var _a;
-        super(part);
-        this.host = (_a = part.options) === null || _a === void 0 ? void 0 : _a.host;
-    }
-    render(number, options) {
-        const lang = connectedElements.get(this.host) || '';
-        return n(lang, number, options);
-    }
-}
-export const formatNumber = directive(FormatNumberDirective);

package/src/fast.ts DELETED Viewed

@@ -1,107 +0,0 @@
-import { connectedElements, detectLanguage, translate as t, formatDate as d, formatNumber as n } from './';
-import type { CaptureType, ExecutionContext, FASTElement } from '@microsoft/fast-element';
-import type { FunctionParams, Translation } from './';
-/**
- * FAST Decorator
- *
- * This class decorator ensures lang is a reactive property and adds and removes the component to and from the
- * connectedElements set.
- */
-export function localize() {
-  return (targetClass: any): typeof targetClass => {
-    return class extends targetClass {
-      constructor() {
-        super();
-      }
-      connectedCallback() {
-        super.connectedCallback();
-        const lang = detectLanguage(this as typeof targetClass);
-        connectedElements.set(this as typeof targetClass, lang);
-      }
-      disconnectedCallback() {
-        super.disconnectedCallback();
-        connectedElements.delete(this as typeof targetClass);
-      }
-      get lang() {
-        return this.getAttribute('lang');
-      }
-      set lang(value: string) {
-        if (value === null || value === undefined) {
-          this.removeAttribute('lang');
-        } else {
-          this.setAttribute('lang', value);
-        }
-        connectedElements.set(this as typeof targetClass, value);
-        this.updateLocalizedTerms();
-      }
-      updateLocalizedTerms() {
-        //
-        // This is a hacky way to force a re-render, but there's no other way to achieve this at the moment. This issue
-        // tracks a proposal to introduce signals that will allow external changes to trigger updates.
-        //
-        // https://github.com/microsoft/fast/issues/5083
-        //
-        this.$fastController.renderTemplate(this.$fastController.template);
-      }
-    };
-  };
-}
-function getLang(source: any) {
-  let lang = '';
-  // A directive may be called from any context. In some cases, such as when contexts are nested, we won't have a
-  // reference to the host element. In that case, we can't provide a value for lang so we return an empty string.
-  if (source instanceof HTMLElement) {
-    lang = connectedElements.get(source) || '';
-  }
-  return lang;
-}
-/**
- * FAST format number directive
- *
- * Formats a number using the element's current language.
- */
-export function translate<TSource, K extends keyof Translation>(
-  context: ExecutionContext | FASTElement | HTMLElement,
-  key: K,
-  ...args: FunctionParams<Translation[K]>
-): CaptureType<TSource> {
-  return t(getLang(context), key, ...args);
-}
-/**
- * FAST format date directive
- *
- * Formats a date using the element's current language.
- */
-export function formatDate<TSource = any>(
-  context: ExecutionContext | FASTElement | HTMLElement,
-  date: Date | string,
-  options?: Intl.DateTimeFormatOptions
-): CaptureType<TSource> {
-  return d(getLang(context), date, options);
-}
-/**
- * FAST format number directive
- *
- * Formats a number using the element's current language.
- */
-export function formatNumber<TSource = any>(
-  context: ExecutionContext | FASTElement | HTMLElement,
-  number: number | string,
-  options?: Intl.DateTimeFormatOptions
-): CaptureType<TSource> {
-  return n(getLang(context), number, options);
-}

package/src/lit.ts DELETED Viewed

@@ -1,108 +0,0 @@
-import { Directive, directive, Part } from 'lit/directive.js';
-import { connectedElements, detectLanguage, formatDate as d, formatNumber as n, translate as t } from './';
-import type { FunctionParams, Translation } from './';
-import type { LitElement } from 'lit';
-/**
- * Lit Decorator
- *
- * This class decorator ensures lang is a reactive property and adds and removes the component to and from the
- * connectedElements set.
- */
-export function localize() {
-  return (targetClass: any): typeof targetClass => {
-    return class extends targetClass {
-      static get properties() {
-        return {
-          // Ensure lang is a watched property
-          lang: { type: String },
-          ...targetClass.properties
-        };
-      }
-      connectedCallback() {
-        super.connectedCallback();
-        const lang = detectLanguage(this as typeof targetClass);
-        connectedElements.set(this as typeof targetClass, lang);
-      }
-      disconnectedCallback() {
-        super.disconnectedCallback();
-        connectedElements.delete(this as typeof targetClass);
-      }
-      updateLocalizedTerms() {
-        this.requestUpdate();
-      }
-    };
-  };
-}
-/**
- * Lit translate directive
- *
- * Translates a term using the element's current language.
- */
-class TranslateDirective extends Directive {
-  host: HTMLElement | undefined;
-  constructor(part: Part) {
-    super(part);
-    this.host = part.options?.host as HTMLElement;
-  }
-  render<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>) {
-    const lang = connectedElements.get(this.host as LitElement) || '';
-    return t(lang, key, ...args);
-  }
-}
-const litDirective = directive(TranslateDirective);
-export function translate<K extends keyof Translation>(key: K, ...args: FunctionParams<Translation[K]>) {
-  return litDirective(key, ...args);
-}
-/**
- * Lit format date directive
- *
- * Formats a date using the element's current language.
- */
-class FormatDateDirective extends Directive {
-  host: HTMLElement | undefined;
-  constructor(part: Part) {
-    super(part);
-    this.host = part.options?.host as HTMLElement;
-  }
-  render(date: Date | string, options?: Intl.DateTimeFormatOptions) {
-    const lang = connectedElements.get(this.host as LitElement) || '';
-    return d(lang, date, options);
-  }
-}
-export const formatDate = directive(FormatDateDirective);
-/**
- * Lit format number directive
- *
- * Formats a number using the element's current language.
- */
-class FormatNumberDirective extends Directive {
-  host: HTMLElement | undefined;
-  constructor(part: Part) {
-    super(part);
-    this.host = part.options?.host as HTMLElement;
-  }
-  render(number: number | string, options?: Intl.NumberFormatOptions) {
-    const lang = connectedElements.get(this.host as LitElement) || '';
-    return n(lang, number, options);
-  }
-}
-export const formatNumber = directive(FormatNumberDirective);