https://github.com/nabeghe/light-localization
A light weight and path-based PHP localization library that translations are loaded up when needed.
https://github.com/nabeghe/light-localization
library localization localizer php php-library php-localization php-translation
Last synced: about 1 month ago
JSON representation
A light weight and path-based PHP localization library that translations are loaded up when needed.
- Host: GitHub
- URL: https://github.com/nabeghe/light-localization
- Owner: nabeghe
- License: mit
- Created: 2024-01-19T00:17:14.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2025-07-03T12:36:24.000Z (9 months ago)
- Last Synced: 2025-09-14T14:34:29.860Z (7 months ago)
- Topics: library, localization, localizer, php, php-library, php-localization, php-translation
- Language: PHP
- Homepage:
- Size: 31.3 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Light Localization
> A lightweight, key-value & path-based PHP localization library.
> Translation groups are loaded lazily — only when first accessed.
## Requirements
- PHP >= 7.4
- [nabeghe/atlin](https://github.com/nabeghe/atlin-php)
## Installation
```bash
composer require nabeghe/light-localization
```
## Directory Structure
Organize your translations like this:
```
/langs/
/en/
main.php
messages.php
extra.atlin
/fa/
main.php
extra.atlin
```
- Each sub-directory represents a **locale code**.
- Each file inside is a **translation group** (identified by filename without extension).
- Files can be `.php` (returning an array) or `.atlin` format.
- `.atlin` files take precedence over `.php` when both exist for the same group name.
## Quick Start
```php
use Nabeghe\LightLocalization\Localizer;
$en = new Localizer(__DIR__ . '/langs', 'en');
$fa = new Localizer(__DIR__ . '/langs', 'fa', $en); // $en is the fallback
// Reads from main.php (default group)
echo $fa->get('title');
// Reads from messages.php
echo $fa->get('success', 'messages');
// Returns a random item when the value is an array
echo $fa->rnd('greet');
```
## Constructor
```php
new Localizer(
string $path,
string $locale = 'en',
Localizer|string|null $fallback = null,
?string $defaultTranslationText = null,
?Atlin $atlin = null
);
```
| Parameter | Description |
|---|---|
| `$path` | Absolute path to the translations root directory |
| `$locale` | Active locale code |
| `$fallback` | Another `Localizer` to chain, or a plain string used as default |
| `$defaultTranslationText` | Returned when no translation is found anywhere in the chain |
| `$atlin` | Custom `Atlin` instance; created automatically if `null` |
## Translation Files
### PHP
Return a plain associative array. Values can be strings or arrays of strings (for `rnd()`).
```php
'Hello World',
'greet' => ['Hi!', 'Hey!', 'Hello!'],
];
```
### Atlin
Standard key-value `.atlin` format:
```
@title
Hello Atlin World
@description
A lightweight localization library
```
## API Reference
### Locale
| Method | Description |
|---|---|
| `getLocale(): string` | Returns the current locale |
| `setLocale(string $locale): void` | Changes the locale and clears all loaded groups |
| `getLastLocale(): ?string` | Locale used in the most recent successful lookup |
### Lookup
| Method | Description |
|---|---|
| `get(string $key, string $group = 'main', bool $deep = true): ?string` | Returns the translation for a key |
| `rnd(string $key, string $group = 'main', bool $deep = true): ?string` | Like `get()`, but picks a random item when the value is an array |
| `has(string $key, string $group = 'main', bool $deep = true): bool` | Checks whether a key exists |
### Group Management
| Method | Description |
|---|---|
| `load(string $group): bool` | Loads a translation group from disk |
| `refresh(): void` | Reloads all currently loaded groups |
| `reset(): void` | Clears all loaded groups from memory |
| `resetTranslation(string $group): bool` | Removes a specific group from memory |
| `hasTranslation(string $group): bool` | Checks whether a group is loaded in memory |
| `hasTranslationFile(string $group): bool` | Checks whether a group file exists on disk |
### Fallback & Default Text
| Method | Description |
|---|---|
| `getFallback()` | Returns the current fallback (Localizer or string) |
| `setFallback(Localizer\|string\|null $fallback): void` | Sets a new fallback |
| `getDefaultTranslationText(): ?string` | Returns the static default text |
| `setDefaultTranslationText(?string $text): void` | Sets the static default text |
## Fallback Chain
When a key is not found in the active locale, the library resolves it in this order:
1. Current locale group (lazy-loaded from disk)
2. Fallback `Localizer` (if provided), recursively
3. Fallback string (if provided instead of a Localizer)
4. `defaultTranslationText` (constructor parameter / setter)
5. `null`
## Running Tests
```bash
composer test
```
## License
Licensed under the [MIT License](LICENSE.md).