Internationalization (i18n) support for Alpine.js
npm install alpinejs-i18nInternationalization (i18n) support for Alpine.js (unofficial)
This plugin allow you to easily use localization in your Alpine.js projects!
It provide two _magic helpers_ that you can use to localize strings in your Alpine.js websites & apps.
Version ^2.x for Alpine v3.
Version 1.0.0 for Alpine v2.
#### Demo
- Easy localization of strings using a magic helper
- Support variables in strings!
- Setting & getting current locale using a magic helper as well
- Automatically update affected components on locale change!
- Can be easily used outside of Alpine.js components (in Javascript)
- Typescript support.
``html`
`
npm install alpinejs-i18n
`js
import AlpineI18n from 'alpinejs-i18n';
import Alpine from 'alpinejs';
document.addEventListener('alpine-i18n:ready', function () {
// ... scroll to Usage to see where locale and messages came from
window.AlpineI18n.create(locale, messages);
});
Alpine.plugin(AlpineI18n);
Alpine.start();
`
Add the following
`
In Javascript, after importing alpinejs-i18n:
`js
// the default locale
// you can for example take it from the URL.
let locale = 'en';
// the translation data
// you can load/fetch these from files or keep them hardcoded.
let messages = {
en: {
basic: 'button',
// can have variables
var: 'hello, {name}',
// can be nested
deep: {
one: 'one',
two: 'two',
},
},
ar: {
basic: 'زر',
var: 'مرحبا, {name}',
deep: {
one: 'واحد',
two: 'اثنان',
},
},
};
// finally, pass them to AlpineI18n:
document.addEventListener('alpine-i18n:ready', function () {
window.AlpineI18n.create(locale, messages);
});
`
#### $t magic helper
Using the $t magic helper, you can display the translation for the current locale
Following the example settings above:
`html`
This will make the button's text "button".
##### Using variables in strings
Using variables in translation strings is easy:
`html`
This will make the span's text "hello, rafik"!
#### $locale magic helper
##### Setting the locale
$locale('ar') will set the locale to ar and refresh all Alpine components.
##### Getting the current locale
$locale() (without any argument) will get the current locale. (ar)
#### Events
- alpine-i18n:locale-change is dispatched to document when the locale changes.alpine-i18n:ready
- is dispatched to document when the plugin is ready.
#### Fallback Locale
to set a fallback locale for partially-translated values:
`js`
document.addEventListener('alpine-i18n:ready', function () {
window.AlpineI18n.fallbackLocale = 'en';
}
#### Changing writing direction based on locale
`html`
> NOTE: If you want to set it on the entire body, do not make the body an Alpine Component!
> Use this method from Javascript instead!
> The reason for not making body an Alpine component is because it can affect the performance of the site, if the page is big.
#### Usage from Javascript
All features can be used outside Alpine.js components, meaning from Javascript!
> If you're inside of a module, append window. to AlpineI18n. (becomes window.AlpineI18n)
##### Localizing strings t()
`js`
AlpineI18n.t('key', {var: 'val})
##### Getting & Setting Locale
Getting the locale
`js`
AlpineI18n.locale;
Setting the locale
`js`
AlpineI18n.locale = 'ar';
##### Changing writing direction from Javascript
`html``
This projects follow the Semantic Versioning guidelines.
Community project by @rehhouari, not affiliated with Alpine.js team.
- @KevinBatdorf for the constant feedback and help.
Copyright (c) 2024 Rafik El Hadi Houari and contributors.
Licensed under the MIT license, see LICENSE.md for details.