# 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');
```