First Commit

README.md

@@ -0,0 +1,134 @@
+# 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');
+```