Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
@shoelace-style/localize
Advanced tools
A micro library for localizing custom elements using Lit's Reactive Controller model.
This zero-dependency micro library does not aim to replicate a full-blown localization tool. For that, you should use something like i18next. What this library does do is provide a lightweight, Reactive Controller for sharing and applying translations across one or more custom elements in a component library.
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!
Here's an example of how this library can be used to create a localized custom element with Lit.
import { LocalizeController, registerTranslation } from '@shoelace-style/localize';
// Note: translations can also be lazy loaded (see "Registering Translations" below)
import en from '../translations/en';
import es from '../translations/es';
registerTranslation(en, es);
@customElement('my-element')
export class MyElement extends LitElement {
private localize = new LocalizeController(this);
@property() lang: string;
render() {
return html`
<h1>${this.localize.term('hello_world')}</h1>
`;
}
}
To set the page locale, apply the desired lang
attribute to the <html>
element.
<html lang="es">
...
</html>
Changes to <html lang>
will trigger an update to all localized components automatically.
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?
#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.
<my-element close-label="${t('close')}">
...
</my-element>
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 not intended to solve localization at the framework level. There are much better tools for that.
To achieve this goal, we lean on HTML’s 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 lang="en">
<body>
<my-element>This element will be English</my-element>
<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 that listens for lang
changes on <html>
.
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 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>
.
First, install the library.
npm install @shoelace-style/localize
Next, follow these steps to localize your components.
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.
// en.ts
import type { Translation } from '@shoelace-style/localize';
const translation: Translation = {
$code: 'en',
$name: 'English',
$dir: 'ltr',
// Simple terms
upload: 'Upload',
// Terms with placeholders
greetUser: (name: string) => `Hello, ${name}!`,
// Plurals
numFilesSelected: (count: number) => {
if (count === 0) return 'No files selected';
if (count === 1) return '1 file selected';
return `${count} files selected`;
}
};
export default translation;
Once you've created a translation, you need to register it before use. To register a translation, call the registerTranslation()
method. This example imports and register two translations up front.
import { registerTranslation } from '@shoelace-style/localize';
import en from './en';
import es from './es';
registerTranslation(en, es);
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.
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.
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.
Here's a sample function that dynamically loads a translation.
import { registerTranslation } from '@shoelace-style/localize';
async function changeLanguage(lang) {
const availableTranslations = ['en', 'es', 'fr', 'de'];
if (availableTranslations.includes(lang)) {
const translation = await import(`/path/to/translations/${lang}.js`);
registerTranslation(translation);
}
}
You can use the LocalizeController
with any library that supports Lit's Reactive Controller pattern. In Lit, a localized custom element will look something like this.
import { LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { LocalizeController } from '@shoelace-style/localize/dist/lit.js';
@customElement('my-element')
export class MyElement extends LitElement {
private localize = new LocalizeController(this);
// Make sure to make `dir` and `lang` reactive so the component will respond to changes to its own attributes
@property() dir: string;
@property() lang: string;
render() {
return html`
<!-- Terms -->
${this.localize.term('hello')}
<!-- Dates -->
${this.localize.date('2021-09-15 14:00:00 ET'), { month: 'long', day: 'numeric', year: 'numeric' }}
<!-- 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()}
`;
}
}
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.
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()
!
Intl
APIslang
attributeFAQs
A micro library for localizing custom elements using Lit's Reactive Controller model.
We found that @shoelace-style/localize demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.