alpinejs-i18n

v2.4.2

Published

10 months ago

Internationalization (i18n) support for Alpine.js

Downloads

1,270

0High
0Medium
0Low

rehhouari

i18n Plugin for Alpine.js

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

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.

Demo

You can implement loading locales from files. for example, see my Alpine.js template rapide

Features

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.

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

@KevinBatdorf for the constant feedback and help.

License

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