https://github.com/profullstack/localizer
A simple and lightweight localization and internationalization library for JavaScript applications. Works in both browser and Node.js environments.
https://github.com/profullstack/localizer
Last synced: 28 days ago
JSON representation
A simple and lightweight localization and internationalization library for JavaScript applications. Works in both browser and Node.js environments.
- Host: GitHub
- URL: https://github.com/profullstack/localizer
- Owner: profullstack
- Created: 2025-04-26T13:02:05.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-05-15T09:02:24.000Z (about 1 year ago)
- Last Synced: 2025-12-27T00:52:58.888Z (6 months ago)
- Language: TypeScript
- Size: 80.1 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# @profullstack/localizer
A simple localization and internationalization library with RTL support.
## Features
- Simple API for translating text
- Support for multiple languages with fallback
- Interpolation of variables in translations
- Support for pluralization
- Right-to-Left (RTL) language support
- DOM translation utilities for automatic UI updates
- MutationObserver integration for dynamic content
- Works in both browser and Node.js environments
## Installation
```bash
npm install @profullstack/localizer
# or
yarn add @profullstack/localizer
# or
pnpm add @profullstack/localizer
```
## Usage
### Basic Usage
```javascript
import { localizer, _t } from '@profullstack/localizer';
// Load translations
localizer.loadTranslations('en', {
'hello': 'Hello',
'welcome': 'Welcome, ${name}!'
});
localizer.loadTranslations('fr', {
'hello': 'Bonjour',
'welcome': 'Bienvenue, ${name}!'
});
localizer.loadTranslations('ar', {
'hello': 'مرحبا',
'welcome': 'مرحبًا، ${name}!'
});
// Set the current language
localizer.setLanguage('fr');
// Translate a key
console.log(_t('hello')); // Output: Bonjour
// Translate with interpolation
console.log(_t('welcome', { name: 'John' })); // Output: Bienvenue, John!
```
### DOM Translation
The library provides utilities for automatically translating DOM elements:
```javascript
// Add data-i18n attributes to your HTML
//
Welcome
//
// Translate all elements with i18n attributes in the document
localizer.translateDOM();
// Translate elements within a specific container
const container = document.querySelector('.my-container');
localizer.translateContainer(container);
// Set up automatic translation of dynamically added elements
localizer.observeDOM();
```
### RTL Support
The library automatically detects Right-to-Left (RTL) languages and provides methods to check if a language is RTL:
```javascript
// Check if the current language is RTL
const isRTL = localizer.isRTL();
// Check if a specific language is RTL
const isArabicRTL = localizer.isLanguageRTL('ar'); // true
const isEnglishRTL = localizer.isLanguageRTL('en'); // false
// Apply RTL direction to the document
localizer.applyRTLToDocument();
// The library dispatches an event when the language changes
window.addEventListener('language-changed', (event) => {
const { language, previousLanguage, isRTL } = event.detail;
// RTL direction is automatically applied when using applyRTLToDocument()
// but you can also handle it manually:
document.documentElement.dir = isRTL ? 'rtl' : 'ltr';
if (isRTL) {
document.body.classList.add('rtl');
} else {
document.body.classList.remove('rtl');
}
});
```
### Loading Translations from JSON Files
```javascript
// In a browser environment
async function loadTranslations() {
await localizer.loadTranslationsFromUrl('en', '/i18n/en.json');
await localizer.loadTranslationsFromUrl('fr', '/i18n/fr.json');
await localizer.loadTranslationsFromUrl('ar', '/i18n/ar.json');
// Set initial language based on browser preference
const browserLang = navigator.language.split('-')[0];
if (localizer.getAvailableLanguages().includes(browserLang)) {
localizer.setLanguage(browserLang);
} else {
localizer.setLanguage('en'); // fallback
}
}
```
## API Reference
### Localizer Class
#### Constructor
```javascript
const localizer = new Localizer(options);
```
Options:
- `defaultLanguage`: The default language to use (default: 'en')
- `fallbackLanguage`: The fallback language to use when a translation is not found (default: 'en')
- `translations`: Initial translations object (default: {})
- `interpolationStart`: The start delimiter for interpolation (default: '${')
- `interpolationEnd`: The end delimiter for interpolation (default: '}')
- `rtlLanguages`: Array of RTL language codes (default: ['ar', 'he', 'fa', 'ur'])
#### Methods
##### Core Methods
- `loadTranslations(language, translations)`: Load translations for a language
- `setLanguage(language)`: Set the current language
- `getLanguage()`: Get the current language
- `getAvailableLanguages()`: Get an array of available language codes
- `translate(key, options)`: Translate a key with optional interpolation and pluralization
- `loadTranslationsFromUrl(language, url)`: Load translations from a JSON file (browser only)
- `isRTL()`: Check if the current language is RTL
- `isLanguageRTL(language)`: Check if a specific language is RTL
##### DOM Methods (Browser Only)
- `translateDOM(container?)`: Translate all elements with i18n attributes in the document or container
- `translateContainer(container)`: Translate all elements with i18n attributes in a specific container
- `observeDOM(rootElement?)`: Set up a MutationObserver to automatically translate new elements
- `stopObservingDOM()`: Stop observing DOM changes
- `applyRTLToDocument()`: Apply RTL direction to the document based on the current language
### Translation Function
```javascript
_t(key, options);
```
Parameters:
- `key`: The translation key
- `options`: Options for translation (interpolation values, count for pluralization, etc.)
## DOM Translation Attributes
The library supports the following data attributes for DOM translation:
- `data-i18n`: Translates the element's text content
- `data-i18n-placeholder`: Translates the element's placeholder attribute
- `data-i18n-title`: Translates the element's title attribute
- `data-i18n-html`: Translates the element's innerHTML (use with caution)
- `data-i18n-params`: JSON string of parameters for interpolation (used with data-i18n)
Example:
```html
Welcome
Click me
Hello, John!
```
## License
MIT