A simple localization utility for Alpine.js applications.
This package helps you add localization support to your Alpine.js project by dynamically loading language files and providing a convenient $t magic property for translations. Just 0.9 KB in total size
Localizations files should now be named like this en.json instead of en-US.json
This makes it a bit simpler to declare localizations for all variations of a language such as en-AU or en-GB
alpine-localizations will automatically fetch the appropriate localization file based on the user's browser language (navigator.language).
For example, if navigator.language is en, it will attempt to fetch:
/localizations/en.json
Use the $t magic property to reference localization keys in your Alpine.js components:
<div x-data>
<h1 x-text="$t.greeting"></h1>
<input type="text" :placeholder="$t.welcome">
</div>If the translation key (greeting or welcome) exists in your localization file, it will be displayed. Otherwise, the key itself will be shown as a fallback.
You don’t need to create a localization file for the default language of your website.
By default, the package will attempt to extract content directly from the x-text or :placeholder attributes:
<input :placeholder="$t.email" placeholder="example@mail.com">- The value of the placeholder attribute (example@mail.com) will be shown instantly as the default.
- Once another localization file is loaded, the content will be updated dynamically.
This approach minimizes flickering and ensures that users always see meaningful content, even before localization files are fully loaded.
Remember to add the x-data on any parent where you want to use $t, alpine.js only initializes the component with reactivity when x-data has been added.
Example:
<body x-data="{}">
<h2 class="main-title" x-text="$t.titleTop">Install, build</h2>Add the script link for alpine-localizations before Alpine.js:
<!-- Add alpine-localizations -->
<script src="https://cdn.jsdelivr.net/npm/@octamap/alpine-localizations@2.x.x" defer></script>
<!-- Add Alpine.js -->
<script src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js" defer></script>This ensures the localization store and $t magic property are available when Alpine initializes.
Localization files are expected to be in your static folder (e.g., public/localizations) and named based on the browser's language code.
Example folder structure:
/public
/localizations
en.json
fr.json
{
"greeting": "Hello, World!",
"welcome": "Welcome, {{name}}!"
}<div x-data="{ name: 'John' }">
<p x-text="$t.welcome.replace('{{name}}', name)"></p>
</div>- Localization Key:
"welcome": "Welcome, {{name}}!" - Output: "Welcome, John!"
Dynamic variables allow you to create flexible and reusable localization strings by embedding placeholders that can be replaced with dynamic values at runtime.
In your localization JSON file, use placeholders (\r) for dynamic content:
en.json
{
"checkInboxDescription": "Welcome \r. We have sent a link to your email (\r). Click the link to complete the sign in"
}- Each
\racts as a placeholder for dynamic values that will be passed when calling the translation.
You can use the set() method on your $t magic property to pass values to replace the placeholders.
Example:
<div x-data="{ email: 'adam@mail.com' }">
<span x-text="$t.checkInboxDescription.set('Adam', email)"></span>
</div>-
checkInboxDescriptionis fetched from the localization file. - The
set()method replaces each\rin the order the arguments are passed:- The first
\rbecomes"Adam". - The second
\rbecomes"adam@mail.com".
- The first
<span>Welcome Adam. We have sent a link to your email (adam@mail.com). Click the link to complete the sign in</span>- Ensure the number of placeholders (
\r) in the localization string matches the number of arguments passed toset(). - Use meaningful variable names in your HTML code to improve readability.
- Avoid hardcoding dynamic content directly in localization strings.
Localization File (en.json):
{
"orderSummary": "Hello \r, your order (#\r) for \r items has been confirmed."
}HTML Usage:
<div x-data="{ username: 'John', orderId: '12345', itemCount: 3 }">
<p x-text="$t.orderSummary.set(username, orderId, itemCount)"></p>
</div>Rendered Output:
<p>Hello John, your order (#12345) for 3 items has been confirmed.</p>Dynamic variables make your localizations cleaner, more reusable, and adaptable to various contexts.
- Purpose: Access localization keys.
-
Behavior: Looks for the key in the Alpine store and gracefully falls back to element attributes (
x-text,:placeholder) if the key isn't found.
-
Default Path:
/localizations/ -
File Naming: Must match the
navigator.languagevalue (en.json,fr.json, etc.). - Response Format: Must be valid JSON.
- Always ensure valid JSON in your localization files.
- Provide fallback text using
x-textor:placeholderattributes. - Avoid large localization files to minimize load times.
- Open your browser's Network tab to verify the localization file (
/localizations/{lang}.json) is being fetched correctly. - Check the Console for errors in fetching or parsing JSON files.
Feel free to submit issues or pull requests on the GitHub Repository.
- Fork the repository.
- Create a new branch:
git checkout -b feature/new-feature. - Make your changes.
- Submit a pull request.
This project is licensed under the MIT License. See the LICENSE file for details.
Happy Coding! 🚀