https://github.com/octamap/alpine-localizations
A simple package for alpine.js localizations
https://github.com/octamap/alpine-localizations
alpinejs localizations
Last synced: 8 months ago
JSON representation
A simple package for alpine.js localizations
- Host: GitHub
- URL: https://github.com/octamap/alpine-localizations
- Owner: octamap
- License: mit
- Created: 2025-01-06T19:50:59.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-01-14T14:37:54.000Z (9 months ago)
- Last Synced: 2025-01-14T16:03:40.953Z (9 months ago)
- Topics: alpinejs, localizations
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@octamap/alpine-localizations
- Size: 22.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# **alpine-localizations**
**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
## Breaking changes in V2
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
## 🛠️ **Usage**
### **1. Load Localization Files**
`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
```
### **2. Access Translations with `$t`**
Use the `$t` magic property to reference localization keys in your Alpine.js components:
```html
```
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.
### 3. Default language
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:
```html
```
- 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.
### 4. Remember to add x-data
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:
```html
Install, build
```
---
## 🚀 **Setup**
### **CDN Integration**
Add the script link for `alpine-localizations` **before** Alpine.js:
```html
```
This ensures the localization store and `$t` magic property are available when Alpine initializes.
---
## 📁 **Define Localizations**
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
```
### **Example Localization File (`en.json`)**
```json
{
"greeting": "Hello, World!",
"welcome": "Welcome, {{name}}!"
}
```
## 📝 **Dynamic Content Example**
```html
```
- Localization Key: `"welcome": "Welcome, {{name}}!"`
- Output: **"Welcome, John!"**
## 📝 Dynamic Variables in Localizations (using `\r`)
Dynamic variables allow you to create flexible and reusable localization strings by embedding placeholders that can be replaced with dynamic values at runtime.
### **1. Define Dynamic Variables in Localization Files**
In your localization JSON file, use placeholders (`\r`) for dynamic content:
**`en.json`**
```json
{
"checkInboxDescription": "Welcome \r. We have sent a link to your email (\r). Click the link to complete the sign in"
}
```
- Each `\r` acts as a placeholder for dynamic values that will be passed when calling the translation.
---
### **2. Usage in HTML with Alpine.js**
You can use the `set()` method on your `$t` magic property to pass values to replace the placeholders.
**Example:**
```html
```
### **How it works:**
1. `checkInboxDescription` is fetched from the localization file.
2. The `set()` method replaces each `\r` in the order the arguments are passed:
- The first `\r` becomes `"Adam"`.
- The second `\r` becomes `"adam@mail.com"`.
### **Rendered Output:**
```html
Welcome Adam. We have sent a link to your email (adam@mail.com). Click the link to complete the sign in
```
---
### **3. Best Practices for Dynamic Variables**
- Ensure the number of placeholders (`\r`) in the localization string matches the number of arguments passed to `set()`.
- Use meaningful variable names in your HTML code to improve readability.
- Avoid hardcoding dynamic content directly in localization strings.
---
### **4. Advanced Example with Multiple Variables**
**Localization File (`en.json`):**
```json
{
"orderSummary": "Hello \r, your order (#\r) for \r items has been confirmed."
}
```
**HTML Usage:**
```html
```
**Rendered Output:**
```html
Hello John, your order (#12345) for 3 items has been confirmed.
```
Dynamic variables make your localizations cleaner, more reusable, and adaptable to various contexts.
## 📦 **API Reference**
### `$t` Magic Property
- **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.
---
## 🌍 **Localization File Fetching**
- **Default Path:** `/localizations/`
- **File Naming:** Must match the `navigator.language` value (`en.json`, `fr.json`, etc.).
- **Response Format:** Must be valid JSON.
---
## ✅ **Best Practices**
- Always ensure valid JSON in your localization files.
- Provide fallback text using `x-text` or `:placeholder` attributes.
- Avoid large localization files to minimize load times.
---
## 🐞 **Debugging**
- 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.
---
## 🤝 **Contributing**
Feel free to submit issues or pull requests on the [GitHub Repository](https://github.com/octamap/alpine-localizations).
1. Fork the repository.
2. Create a new branch: `git checkout -b feature/new-feature`.
3. Make your changes.
4. Submit a pull request.
---
## 📜 **License**
This project is licensed under the **MIT License**. See the [LICENSE](./LICENSE) file for details.
---
**Happy Coding! 🚀**