135 lines
3.2 KiB
Markdown
135 lines
3.2 KiB
Markdown
# urfat/lang
|
|
|
|
A simple, zero-dependency PHP internationalization (i18n) library. It auto-discovers translation files from your app directories and caches them in the session or Memcached.
|
|
|
|
## Requirements
|
|
|
|
- PHP 8.0+
|
|
- `ext-memcached` _(optional, only for Memcached caching)_
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
composer require inforsistemas/lang
|
|
```
|
|
|
|
## How it works
|
|
|
|
The library scans your app directories recursively for files matching the pattern `lang/*.php`. Each file defines a `$lang` array where the filename (without `.php`) becomes the locale key.
|
|
|
|
**File:** `app/MyModule/lang/en.php`
|
|
```php
|
|
<?php
|
|
$lang["my_module"]["greeting"] = "Hello, World!";
|
|
$lang["my_module"]["farewell"] = "Goodbye!";
|
|
```
|
|
|
|
**File:** `app/MyModule/lang/pt_br.php`
|
|
```php
|
|
<?php
|
|
$lang["my_module"]["greeting"] = "Olá, Mundo!";
|
|
$lang["my_module"]["farewell"] = "Tchau!";
|
|
```
|
|
|
|
The structure loaded into memory is:
|
|
```
|
|
$_LANG[locale][module][string_key] = "value"
|
|
```
|
|
|
|
## Usage
|
|
|
|
### 1. Build the string database
|
|
|
|
Call `buildStrings()` once at bootstrap, passing one or more directories to scan.
|
|
|
|
```php
|
|
use Lang\Lang;
|
|
|
|
// Single directory
|
|
Lang::buildStrings('app/');
|
|
|
|
// Multiple directories
|
|
Lang::buildStrings(['app/', 'plugins/']);
|
|
```
|
|
|
|
### 2. Retrieve a string
|
|
|
|
```php
|
|
// Get a single string (defaults to 'en' locale)
|
|
Lang::getString('greeting', 'my_module'); // "Hello, World!"
|
|
Lang::getString('greeting', 'my_module', 'pt_br'); // "Olá, Mundo!"
|
|
|
|
// Get all strings for a module
|
|
Lang::getStrings('my_module'); // ['greeting' => 'Hello, World!', ...]
|
|
Lang::getStrings('my_module', 'pt_br'); // ['greeting' => 'Olá, Mundo!', ...]
|
|
```
|
|
|
|
If a key is not found, the key name itself is returned as a fallback.
|
|
|
|
## Caching
|
|
|
|
Strings are cached after the first directory scan to avoid re-reading files on every request.
|
|
|
|
### SESSION (default)
|
|
|
|
No configuration needed. Strings are stored in `$_SESSION['cache']['strings']`.
|
|
|
|
```php
|
|
Lang::buildStrings('app/'); // uses SESSION by default
|
|
Lang::buildStrings('app/', false, 'SESSION'); // explicit
|
|
```
|
|
|
|
### Memcached
|
|
|
|
```php
|
|
$memcached = new Memcached();
|
|
$memcached->addServer('127.0.0.1', 11211);
|
|
|
|
Lang::setMemcached($memcached, 'my_app_lang', 3600); // key, ttl (seconds)
|
|
Lang::buildStrings('app/', false, 'MEMCACHED');
|
|
```
|
|
|
|
### Forcing a rebuild
|
|
|
|
Pass `true` as the second argument to ignore the cache and rescan all files.
|
|
|
|
```php
|
|
Lang::buildStrings('app/', rebuild: true);
|
|
```
|
|
|
|
## API Reference
|
|
|
|
```php
|
|
// Configure Memcached (optional)
|
|
Lang::setMemcached(\Memcached $instance, string $key = 'urfat_lang_strings', int $ttl = 3600): void
|
|
|
|
// Scan directories and populate the string database
|
|
Lang::buildStrings(string|array $folders, bool $rebuild = false, string $cache = 'SESSION'): void
|
|
|
|
// Get a single translated string
|
|
Lang::getString(string $string, string $module = '', string $lang = 'en'): string
|
|
|
|
// Get all strings for a module
|
|
Lang::getStrings(string $module = '', string $lang = 'en'): array
|
|
```
|
|
|
|
## Directory structure example
|
|
|
|
```
|
|
app/
|
|
UserModule/
|
|
lang/
|
|
en.php
|
|
pt_br.php
|
|
OrderModule/
|
|
lang/
|
|
en.php
|
|
pt_br.php
|
|
```
|
|
|
|
```php
|
|
Lang::buildStrings('app/');
|
|
Lang::getString('page_title', 'user_module');
|
|
Lang::getString('page_title', 'order_module', 'pt_br');
|
|
```
|