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

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
$lang["my_module"]["greeting"] = "Hello, World!";
$lang["my_module"]["farewell"] = "Goodbye!";

File: app/MyModule/lang/pt_br.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.

use Lang\Lang;

// Single directory
Lang::buildStrings('app/');

// Multiple directories
Lang::buildStrings(['app/', 'plugins/']);

2. Retrieve a string

// 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'].

Lang::buildStrings('app/');                    // uses SESSION by default
Lang::buildStrings('app/', false, 'SESSION');  // explicit

Memcached

$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.

Lang::buildStrings('app/', rebuild: true);

API Reference

// 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

Lang::buildStrings('app/');
Lang::getString('page_title', 'user_module');
Lang::getString('page_title', 'order_module', 'pt_br');