https://github.com/brightspaceui/localize-behavior
Polymer mixins for localizing web components
https://github.com/brightspaceui/localize-behavior
localization polymer web-components
Last synced: 3 months ago
JSON representation
Polymer mixins for localizing web components
- Host: GitHub
- URL: https://github.com/brightspaceui/localize-behavior
- Owner: BrightspaceUI
- License: apache-2.0
- Created: 2017-09-06T18:19:09.000Z (almost 9 years ago)
- Default Branch: main
- Last Pushed: 2025-06-23T18:19:40.000Z (12 months ago)
- Last Synced: 2025-07-09T11:24:26.183Z (11 months ago)
- Topics: localization, polymer, web-components
- Language: JavaScript
- Homepage:
- Size: 146 KB
- Stars: 0
- Watchers: 16
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
> Building Lit components? Use [BrightspaceUI/core](https://github.com/BrightspaceUI/core) instead.
# @brightspace-ui/localize-behavior
[Polymer](https://www.polymer-project.org) mixin for localization of text, dates, times, numbers and file sizes. Also supports automatic language resolution, timezone and locale overrides.
## Installation
Install from NPM:
```shell
npm install @brightspace-ui/localize-behavior
```
## Usage
```javascript
import '@brightspace-ui/localize-behavior/d2l-localize-behavior.js';
import { mixinBehaviors } from '@polymer/polymer/lib/legacy/class.js';
class MyElement extends mixinBehaviors([
D2L.PolymerBehaviors.LocalizeBehavior
], PolymerElement) {
static get template() {
return html`
[[localize('hello')]]
`;
}
localizeConfig: {
importFunc: async lang => (await import(`./lang/${lang}.js`)).default
}
}
```
### Language Resources
Store localization resources in their own directory with nothing else in it. There should be one JavaScript file for each supported locale.
```javascript
// lang/en.js
export default {
hello: `Hello, {firstName}!`
};
```
```javascript
// lang/fr.js
export default {
hello: `Bonjour, {firstName}!`
};
```
* Always provide files for base languages (e.g. "en", "fr", "pt") so that if the user is using an unsupported regional language (e.g. "en-au", "fr-ca", "pt-br") it can fall back to the base language.
* If there's no entry for a particular language, and no base language, the value of `data-lang-default` on the `` element will be used.
* If no `data-lang-default` is specified, "en" will be used as a last resort.
### `localize()`
The `localize()` method is used to localize a piece of text in the component's `template`.
If the localized string contains arguments, pass them as additional parameters to `localize`:
```javascript
static get template() {
return html`
[[localize('hello', 'firstName', 'Mary')]]
`;
}
```
### Numbers, File Sizes, Dates and Times
While `localize-behavior` does support formatting and parsing numbers, dates and times, instead please use the [https://github.com/BrightspaceUI/intl/](BrightspaceUI/intl) library directly.
## Developing
After cloning the repo, run `npm install` to install dependencies.
### Running the demos
To start a [@web/dev-server](https://modern-web.dev/docs/dev-server/overview/) that hosts the demo page and tests:
```shell
npm start
```
### Testing
To run the full suite of tests:
```shell
npm test
```
Alternatively, tests can be selectively run:
```shell
# eslint
npm run lint:eslint
# unit tests
npm run test:unit
```
### Versioning and Releasing
This repo is configured to use `semantic-release`. Commits prefixed with `fix:` and `feat:` will trigger patch and minor releases when merged to `main`.
To learn how to create major releases and release from maintenance branches, refer to the [semantic-release GitHub Action](https://github.com/BrightspaceUI/actions/tree/main/semantic-release) documentation.