@brightspace-ui/core 2.106.0 → 2.107.0

package/mixins/localize/README.md

@@ -1,135 +1,84 @@
-# Localization Mixins
+# LocalizeMixin
 
-The `LocalizeMixin` and `LocalizeStaticMixin` allow you to localize text in your components and have it displayed to the user in their preferred language.
-
-## Providing Resources
-
-Your component must provide resources by either implementing a `resources` getter for local resources, or a `localizeConfig` getter to fetch resources asynchronously. The `importFunc` method of `localizeConfig` will be called with lowercase languages in preferential order.
+The `LocalizeMixin` allows text in components to be displayed in the user's preferred language.
 
 ## Language Resources
 
-Resources should be key-value JSON objects, where the keys are lowercase strings and the values are in [ICU Message Syntax](https://formatjs.io/docs/core-concepts/icu-syntax/) format.
+Resources are stored as key-value JSON objects.
 
-The ICU Message Syntax supports some cool features, such as: [simple arguments](https://formatjs.io/docs/core-concepts/icu-syntax/#simple-argument), the [`{select}` format](https://formatjs.io/docs/core-concepts/icu-syntax/#select-format) and [pluralization](https://formatjs.io/docs/core-concepts/icu-syntax/#plural-format).
+### Keys
 
-**Note:** Avoid using the ICU Message Syntax number, date and time formatting functionality. D2L allows our users to customize how these are localized, so use [@brightspace-ui/intl](https://github.com/BrightspaceUI/intl)'s `formatNumber`, `formatDate` and `formatTime` instead.
-
-Example:
+The key should succinctly and uniquely describe the text being localized. `camelCase` is recommended, although `snake_case` and `kebab-case` are also supported.
 
-```javascript
-{
-  "hello": "Hello {firstName}!",
-  "goodbye": "Goodbye."
-}
-```
+For large projects, terms may be grouped using the `:` character. For example: `parentGroup:subGroup:termName`.
 
-Always provide language resources for base languages (e.g. `en`, `fr`, `pt`, etc.). That way, if the user prefers a regional language (e.g. `pt-br`) that isn't recognized, it can fall back to the base language.
+### Values
 
-### Static vs. Dynamic Resources
+Term values must conform to the [ICU Message Syntax](https://formatjs.io/docs/core-concepts/icu-syntax/) format. It supports features such as: [simple arguments](https://formatjs.io/docs/core-concepts/icu-syntax/#simple-argument), the [`{select}` format](https://formatjs.io/docs/core-concepts/icu-syntax/#select-format) and [pluralization](https://formatjs.io/docs/core-concepts/icu-syntax/#plural-format).
 
-For components with local resources, use the `LocalizeStaticMixin` and implement a `static` `resources` getter that returns the local resources synchronously. To get resources asynchronously, use the `LocalizeMixin` and implement a `static` `localizeConfig` getter that returns details about where to find your resources.
+> **Note:** Avoid using the ICU Message Syntax number, date and time formatting functionality. Brightspace allows customization of how these are localized, so use [@brightspace-ui/intl](https://github.com/BrightspaceUI/intl)'s `formatNumber`, `formatDate` and `formatTime` instead.
 
-#### Example 1: Static Resources
+### Files
 
-If your component has a small number of translations, it may make sense to store them locally within the component in a constant.
+Store localization resources in their own directory with nothing else in it. There should be one JavaScript file for each supported locale.
 
 ```javascript
-import { LocalizeStaticMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
-
-class MyComponent extends LocalizeStaticMixin(LitElement) {
-
-  static get resources() {
-    return {
-      'en': {
-        hello: 'Hello {firstName}!'
-      },
-      'fr': {
-        hello: 'Bonjour {firstName}!'
-      },
-      ...
-    };
-  }
-
-}
+// en.js
+export default {
+  "hello": "Hello {firstName}!"
+};
 ```
-#### Example 2: Dynamically Imported Resources
-
-This approach is better for components with many language resources. By importing them dynamically, only the resources for the requested language are actually fetched and downloaded.
-
-Store your resources in individual files, one for each language:
 ```javascript
-// en.js
+// fr.js
 export default {
-  'hello': 'Hello {firstName}!'
+  "hello": "Bonjour {firstName}!"
 };
 ```
 
-**Note:** To avoid accidental imports and errors, your resource files should have a dedicated directory with nothing else in it.
+Always provide language resources for base languages (e.g. `en`, `fr`, `pt`). That way, if the user prefers a regional language (e.g. `pt-br`) that isn't recognized, it can fall back to the base language (`pt`).
+
+## Using `LocalizeMixin`
+
+The component should import and extend `LocalizeMixin`:
 
-Then create your `localizeConfig` getter:
 ```javascript
 import { LocalizeMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
 
 class MyComponent extends LocalizeMixin(LitElement) {
 
-  static get localizeConfig() {
-    return {
-       // Import path must be relative
-      importFunc: async lang => (await import(`../lang/${lang}.js`)).default,
-      // Optionally enable OSLO
-      osloCollection: '@d2l\\my-project\\myComponent',
-    };
-  }
 }
 ```
-Occasionally, it may be desirable to localize based on the user's browser settings. To do this, add `useBrowserLangs: true` to your `localizeConfig` object. This option should only be used if *all* supported *locales* have corresponding files named with their 4-character locale code, and all supported *languages*, in addition, have 2-character files. (e.g. `en-us.js`, `en-ca.js` and `en.js`)
 
-If your build system does not support variable dynamic imports, you'll need to manually set up imports for each supported language:
+Implement a static getter for `localizeConfig` that defines `importFunc()`. It will be passed a language which can subsequently be dynamically imported from the location of the component's resources.
+
+The dynamic import path must be relative.
 
 ```javascript
 static get localizeConfig() {
   return {
-    importFunc: async lang => {
-      switch (lang) {
-        case 'en':
-          return (await import('./locales/en.js')).default;
-        case 'fr':
-          return (await import('./locales/fr.js')).default;
-        ...
-      }
-    }
+    importFunc: async lang => (await import(`../lang/${lang}.js`)).default,
   };
 }
 ```
 
-**Note:** If using `LocalizeCoreElement` or a mixin that utilizes `LocalizeCoreElement` as well as `LocalizeMixin` or a mixin that uses `LocalizeMixin`, `LocalizeMixin` **must** appear before `LocalizeCoreElement` in the chain. For example:
-
-```javascript
-import { LocalizeCoreElement } from '@brightspace-ui/core/helpers/localize-core-element.js';
-import { LocalizeMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
-
-class MyComponent extends LocalizeMixin(LocalizeCoreElement(LitElement)) {
-  ...
-}
-```
-
-## `localize()`
+### `localize()`
 
-Once your localization resources are available, the `localize()` method is used to localize a piece of text in your `render()` method.
+The `localize()` method is used to localize a piece of text in the component's `render()` method.
 
-If your localized string contains arguments, pass them as a key-value object as the 2nd parameter:
+If the localized string contains arguments, pass them as a key-value object as the 2nd parameter:
 
 ```javascript
 render() {
-  return html`<p>${this.localize('hello', { firstName: 'Mary' })}</p>`;
+  const message = this.localize('hello', { firstName: 'Mary' });
+  return html`<p>${message}</p>`;
 }
 ```
 
-## `localizeHTML()`
+### `localizeHTML()`
 
 Rich formatting can be included in localization resources and safely converted to HTML with the `localizeHTML()` method.
 
-### Basic Formatting
+#### Basic Formatting
 
 The following formatting elements are supported out-of-the-box:
 
@@ -144,7 +93,19 @@ Remember that `<strong>` is for content of greater importance (browsers show thi
 
 Similarly `<em>` *emphasizes* a particular piece of text (browsers show this visually using italics), whereas `<i>` only italicizes the text visually without emphasis.
 
-### Links
+Example:
+
+```json
+{
+  "myTerm": "This is <b>bold</b> but <em>not</em> all that <strong>important</strong>."
+}
+```
+
+```javascript
+this.localizeHTML('myTerm');
+```
+
+#### Links
 
 To wrap text in [a link](../../components/link/), define a unique tag in the localization resource:
 
@@ -164,7 +125,7 @@ this.localizeHTML('myTerm', {
 });
 ```
 
-### Help Tooltips
+#### Help Tooltips
 
 To use a [help tooltip](../../components/tooltip/), define a unique tag in the localization resource in addition to the tooltip's text:
 
@@ -175,7 +136,7 @@ To use a [help tooltip](../../components/tooltip/), define a unique tag in the l
 }
 ```
 
-Then import `generateTooltipHelp` and pass it the tooltip term value:
+Then import `generateTooltipHelp` and pass it the tooltip contents value:
 
 ```javascript
 import { generateTooltipHelp } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
@@ -184,3 +145,38 @@ this.localizeHTML('octopus', {
   tooltip: generateTooltipHelp({ contents: this.localize('cephalopodTooltip') })
 });
 ```
+
+## Off-Stack Language Overrides
+
+To enable OSLO, map the project's localization resources to a language collection in Brightspace by defining `osloCollection` in `localizeConfig`:
+
+```javascript
+static get localizeConfig() {
+  return {
+    osloCollection: '@d2l\\my-project\\myComponent',
+  };
+}
+```
+
+> **Important:** When defining language resource keys, avoid using the Full Stop (`.`) character for grouping. OSLO does not support it.
+
+## Advanced
+
+### Chaining `LocalizeMixin`
+
+If combining `LocalizeMixin` with `LocalizeCoreElement` (or a mixin that uses `LocalizeCoreElement`), `LocalizeMixin` **must** appear before `LocalizeCoreElement` in the chain.
+
+```javascript
+import { LocalizeCoreElement } from '@brightspace-ui/core/helpers/localize-core-element.js';
+import { LocalizeMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
+
+class MyComponent extends LocalizeMixin(LocalizeCoreElement(LitElement)) {
+  ...
+}
+```
+
+### Ignoring the Brightspace Language
+
+Occasionally, it may be desirable to localize based on the browser's language instead of the language in Brightspace.
+
+To do this, define `useBrowserLangs` as `true` in `localizeConfig`. This option should only be used if all supported locales have corresponding files named with their 4-character and 2-character locale codes (e.g. `en-us.js`, `en-ca.js` and `en.js`).

package/mixins/localize/localize-mixin.js

@@ -230,31 +230,6 @@ export const LocalizeMixin = superclass => class extends _LocalizeMixinBase(supe
 
 };
 
-export const LocalizeStaticMixin = superclass => class extends _LocalizeMixinBase(superclass) {
-
-	static async getLocalizeResources(langs) {
-		let resolvedLang = fallbackLang;
-		const resolvedResources = Object.assign({}, this.resources[fallbackLang]);
-
-		langs.reverse().forEach((lang) => {
-			if (this.resources[lang]) {
-				resolvedLang = lang;
-				Object.assign(resolvedResources, this.resources[lang]);
-			}
-		});
-
-		return {
-			language: resolvedLang,
-			resources: resolvedResources
-		};
-	}
-
-	static get resources() {
-		return { 'en': {} };
-	}
-
-};
-
 export const allowedTags = Object.freeze(['d2l-link', 'd2l-tooltip-help', 'p', 'br', 'b', 'strong', 'i', 'em']);
 
 const markupError = `localizeHTML() rich-text replacements must use localizeMarkup templates with only the following allowed elements: ${allowedTags}. For more information, see: https://github.com/BrightspaceUI/core/blob/main/mixins/localize/`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brightspace-ui/core",
-  "version": "2.106.0",
+  "version": "2.107.0",
   "description": "A collection of accessible, free, open-source web components for building Brightspace applications",
   "type": "module",
   "repository": "https://github.com/BrightspaceUI/core.git",