Internationalization (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.
- 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.
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>npm install alpinejs-i18n
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 <script> to the <head> of your document before including Alpine:
<script type="module">
import AlpineI18n from "https://cdn.jsdelivr.net/npm/[email protected]/dist/module.esm.min.js";
document.addEventListener("alpine-i18n:ready", function () {
// ... scroll to Usage to see where locale and messages came from
window.AlpineI18n.create(locale, messages);
});
document.addEventListener("alpine:init", () => {
window.Alpine.plugin(AlpineI18n);
});
</script>In Javascript, after importing alpinejs-i18n:
// 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);
});Using the $t magic helper, you can display the translation for the current locale
Following the example settings above:
<div x-data>
<button x-text="$t('basic')"></button>
</div>This will make the button's text "button".
Using variables in translation strings is easy:
<span x-text="$t('var', {name: 'rafik'})"></span>This will make the span's text "hello, rafik"!
$locale('ar') will set the locale to ar and refresh all Alpine components.
$locale() (without any argument) will get the current locale. (ar)
alpine-i18n:locale-changeis dispatched todocumentwhen the locale changes.alpine-i18n:readyis dispatched todocumentwhen the plugin is ready.
to set a fallback locale for partially-translated values:
document.addEventListener('alpine-i18n:ready', function () {
window.AlpineI18n.fallbackLocale = 'en';
}<div x-data :dir="{'rtl': $locale() == 'ar'}"></div>NOTE: If you want to set it on the entire
body, do not make thebodyan 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.
All features can be used outside Alpine.js components, meaning from Javascript!
If you're inside of a module, append
window.toAlpineI18n. (becomeswindow.AlpineI18n)
AlpineI18n.t('key', {var: 'val})Getting the locale
AlpineI18n.locale;Setting the locale
AlpineI18n.locale = "ar";<script>
// define the RTL locales you support
var rtlLocales = ["ar", "fa"];
// listen to locale changes
window.addEventListener("alpine-i18n:locale-change", function () {
if (rtlLocales.includes(window.AlpineI18n.locale)) {
document.body.setAttribute("dir", "rtl");
} else {
document.body.removeAttribute("dir");
}
});
</script>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.
