diff --git a/docs/_sidebar.md b/docs/_sidebar.md index f1448adf6..ae51a30bd 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -4,6 +4,7 @@ - [Usage](/getting-started/usage) - [Themes](/getting-started/themes) - [Customizing](/getting-started/customizing) + - [Localization](/getting-started/localization) - Frameworks - [React](/frameworks/react) diff --git a/docs/getting-started/localization.md b/docs/getting-started/localization.md new file mode 100644 index 000000000..a409847cb --- /dev/null +++ b/docs/getting-started/localization.md @@ -0,0 +1,136 @@ +# Localization + +Components can be localized by importing the appropriate translation file and setting the desired [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) on the `` element. Here's an example that renders Shoelace components in Spanish. + +```html + + + + + + + ... + + +``` + +Through the magic of a mutation observer, changing the `lang` attribute will automatically update all localized components to use the new locale. + +?> Shoelace 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](https://www.i18next.com/) if you need to localize content in your app. + +## Available Translations + +Shoelace ships with the following translations. The default is English (US), which also serves as the fallback locale. As such, you do not need to import the English translation. + +- `en` - English (US) +- `de` - German +- `es` - Spanish (Latin America) +- `ja` - Japanese +- `pl` - Polish +- `pt` - Portuguese +- `ru` - Russian + +The location of translations depends on how you're consuming Shoelace. + +- If you're using the CDN, [import them from the CDN](https://www.jsdelivr.com/package/npm/@shoelace-style/shoelace?path=dist%2Ftranslations) +- If you're using a bundler, import them from `@shoelace-style/shoelace/dist/translations/[lang].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. + +```js +// Same as setting +document.documentElement.lang = 'de'; + +// Import the translation +import('/path/to/shoelace/dist/translations/de.js'); +``` + +### Translation Resolution + +The locale set by `` 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: + +1. Look for `es-PE` +2. Look for `es` +3. Fall back to `en` + +Shoelace uses English as a fallback to provide a better experience than rendering nothing or throwing an error. + +### Submitting New Translations or Improvements + +To contribute new translations or improvements to existing translations, please submit a pull request on GitHub. Translations are located in [`src/translations`](https://github.com/shoelace-style/shoelace/blob/next/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](https://github.com/shoelace-style/shoelace/discussions) or ask in the [community chat](https://discord.gg/mg8f26C). + +## Multiple Locales Per Page + +You can use a different locale for an individual component by setting its `lang` attribute. Here's a contrived example to demonstrate. + +```html + + ... + + + + + + +``` + +For performance reasons, the `lang` attribute must be on the component itself, not on an ancestor element. + +```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](https://github.com/whatwg/html/issues/7039) to make this possible. + +## Creating Your Own Translations + +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. + +```js +import { registerTranslation } from '@shoelace-style/shoelace/dist/utilities/localize'; +import type { Translation } from '@shoelace-style/shoelace/dist/utilities/localize'; + +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 + + + + + + + ... + + +``` + +?> 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. diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 864b31816..55a887afe 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -10,6 +10,7 @@ - Includes a dark theme 🌛 - Built with accessibility in mind ♿️ - First-class [React support](/frameworks/react) ⚛️ +- Built-in localization 💬 - Open source 😸 Designed in New Hampshire by [Cory LaViska](https://twitter.com/claviska).