Localization
Components can be localized by importing the appropriate translation file and setting the desired lang
and/or dir
attributes on the <html>
element. Here's an example that renders Web Awesome components in Spanish.
<html lang="es"> <head> <script type="module" src="/path/to/shoelace/dist/translations/es.js"></script> </head> <body> ... </body> </html>
Through the magic of a mutation observer, changing the lang
attribute will automatically update all localized components to use the new locale.
Available Translations Jump to heading
Web Awesome ships with a number of translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation.
Available translations include:
- ar
- cs
- da
- de-ch
- de
- en-gb
- en
- es
- fa
- fi
- fr
- he
- hr
- hu
- id
- it
- ja
- nb
- nl
- nn
- pl
- pt
- ru
- sl
- sv
- tr
- uk
- zh-cn
- zh-tw
You can import translations using the following syntax, where <code>
is replaced with any language code shown above.
import 'https://early.webawesome.com/webawesome@3.0.0-alpha.12/dist/translations/<code>.js';
You do not need to load translations up front. You can import them dynamically even after updating the lang
attribute. Once a translation is registered, localized components will update automatically.
// Same as setting <html lang="de"> document.documentElement.lang = 'de'; // Import the translation import('https://early.webawesome.com/webawesome@3.0.0-alpha.12/dist/translations/<code>.js');
Translation Resolution Jump to heading
The locale set by <html lang="...">
is the default locale for the document. If a country code is provided, e.g. es-PE
for Peruvian Spanish, the localization library will resolve it like this:
- Look for
es-PE
- Look for
es
- Fall back to
en
Web Awesome uses English as a fallback to provide a better experience than rendering nothing or throwing an error.
Submitting New Translations or Improvements Jump to heading
To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in src/translations
and can be edited directly on GitHub if you don't want to clone the repo locally.
Regional translations are welcome! For example, if a German translation (de
) exists it's perfectly acceptable to submit a German (Switzerland) (de-CH
) translation.
If you have any questions, please start a discussion or ask in the community chat.
Web Awesome provides a localization mechanism for component internals. This is not designed to be used as localization tool for your entire application. You should use a more appropriate tool such as i18next if you need to localize content in your app.
Multiple Locales Per Page Jump to heading
You can use a different locale for an individual component by setting its lang
and/or dir
attributes. Here's a contrived example to demonstrate.
<html lang="es"> ... <body> <wa-button><!-- Spanish --></wa-button> <wa-button lang="ru"><!-- Russian --></wa-button> </body> </html>
For performance reasons, the lang
and dir
attributes must be on the component itself, not on an ancestor element.
<html lang="es"> ... <body> <div lang="ru"> <wa-button><!-- still in Spanish --></wa-button> </div> </body> </html>
This limitation exists because there's no efficient way to determine the current locale of a given element in a DOM tree. I consider this a gap in the platform and I've proposed a couple properties to make this possible.
Creating Your Own Translations Jump to heading
You can provide your own translations if you have specific needs or if you don't want to wait for a translation to land upstream. The easiest way to do this is to copy src/translations/en.ts
into your own project and translate the terms inside. When your translation is done, you can import it and use it just like a built-in translation.
Let's create a Spanish translation as an example. The following assumes you're using TypeScript, but you can also create translations with regular JavaScript.
import { registerTranslation } from 'path/to/webawesome.js'; import type { Translation } from 'path/to/webawesome.js'; const translation: Translation = { $code: 'es', $name: 'EspaƱol', $dir: 'ltr', term1: '...', term2: '...', ... }; registerTranslation(translation); export default translation;
Once your translation has been compiled to JavaScript, import it and activate it like this.
<html lang="es"> <head> <script type="module" src="/path/to/es.js"></script> </head> <body> ... </body> </html>
If your translation isn't working, make sure you're using the same localize module when importing registerTranslation
. If you're using a different module, your translation won't be recognized.