The LocalizeMixin
allows text in components to be displayed in the user's preferred language.
Resources are stored as key-value JSON objects.
The key should succinctly and uniquely describe the text being localized. camelCase
is recommended, although snake_case
and kebab-case
are also supported.
For large projects, terms may be grouped using the :
character. For example: parentGroup:subGroup:termName
.
Term values must conform to the ICU Message Syntax format. It supports features such as: simple arguments, the {select}
format and pluralization.
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's
formatNumber
,formatDate
andformatTime
instead.
Store localization resources in their own directory with nothing else in it. There should be one JavaScript file for each supported locale.
// en.js
export default {
"hello": "Hello {firstName}!"
};
// fr.js
export default {
"hello": "Bonjour {firstName}!"
};
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
).
The component should import and extend LocalizeMixin
:
import { LocalizeMixin } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
class MyComponent extends LocalizeMixin(LitElement) {
}
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.
static get localizeConfig() {
return {
importFunc: async lang => (await import(`../lang/${lang}.js`)).default,
};
}
The localize()
method is used to localize a piece of text in the component's render()
method.
If the localized string contains arguments, pass them as a key-value object as the 2nd parameter:
render() {
const message = this.localize('hello', { firstName: 'Mary' });
return html`<p>${message}</p>`;
}
Rich formatting can be included in localization resources and safely converted to HTML with the localizeHTML()
method.
The following formatting elements are supported out-of-the-box:
<p>paragraphs</p>
line<br></br>breaks
(note the end tag is required)<b>bold</b>
<strong>strong</strong>
<i>italic</i>
<em>emphasis</em>
Remember that <strong>
is for content of greater importance (browsers show this visually using bold), while <b>
only bolds the text visually without increasing its importance.
Similarly <em>
emphasizes a particular piece of text (browsers show this visually using italics), whereas <i>
only italicizes the text visually without emphasis.
Example:
{
"myTerm": "This is <b>bold</b> but <em>not</em> all that <strong>important</strong>."
}
this.localizeHTML('myTerm');
To wrap text in a link, define a unique tag in the localization resource:
{
"myTerm": "Create a <linkNew>new assignment</linkNew>."
}
Then import the generateLink
helper and use it to provide the href
and optional target
as replacements:
import { generateLink } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
this.localizeHTML('myTerm', {
linkNew: generateLink({ href: 'new.html', target: '_blank' })
});
To use a help tooltip, define a unique tag in the localization resource in addition to the tooltip's text:
{
"octopus": "An octopus is a member of the <tooltip>cephalopod</tooltip> family.",
"cephalopodTooltip": "Cephalopods are members of the molluscan class Cephalopoda"
}
Then import generateTooltipHelp
and pass it the tooltip contents value:
import { generateTooltipHelp } from '@brightspace-ui/core/mixins/localize/localize-mixin.js';
this.localizeHTML('octopus', {
tooltip: generateTooltipHelp({ contents: this.localize('cephalopodTooltip') })
});
To enable OSLO, map the project's localization resources to a language collection in Brightspace by defining osloCollection
in localizeConfig
:
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.
If combining LocalizeMixin
with LocalizeCoreElement
(or a mixin that uses LocalizeCoreElement
), LocalizeMixin
must appear before LocalizeCoreElement
in the chain.
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)) {
...
}
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
).