Skip to content

rehhouari/alpinejs-i18n

Repository files navigation

i18n Plugin for Alpine.js

Internationalization (i18n) support for Alpine.js (unofficial)

GitHub tag (latest by date) npm bundle size Downloads from Jsdelivr NPM npm Changelog Donate

About

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.

Compatibility

Version ^2.x for Alpine v3.

Version 1.0.0 for Alpine v2.

Features

Installation

CDN

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

NPM

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();

ES6 Module

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>

Usage

1- Setting up the translations and locale.

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);
});

2 - Usage from inside Alpine Components

$t magic helper

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 strings

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 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:

document.addEventListener('alpine-i18n:ready', function () {
    window.AlpineI18n.fallbackLocale = 'en';
}

Extra Tips:

Changing writing direction based on locale

<div x-data :dir="{'rtl': $locale() == 'ar'}"></div>

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()
AlpineI18n.t('key', {var: 'val})
Getting & Setting Locale

Getting the locale

AlpineI18n.locale;

Setting the locale

AlpineI18n.locale = "ar";
Changing writing direction from Javascript
<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>

Versioning

This projects follow the Semantic Versioning guidelines.

Disclaimer

Community project by @rehhouari, not affiliated with Alpine.js team.

Acknowledgments

License

Copyright (c) 2024 Rafik El Hadi Houari and contributors.

Licensed under the MIT license, see LICENSE.md for details.