README

A lightweight, key-value & path-based PHP localization library.
Translation groups are loaded lazily — only when first accessed.

Requirements

• PHP >= 7.4
• nabeghe/atlin

Installation

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

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

new Localizer(
    string $path,
    string $locale = 'en',
    Localizer|string|null $fallback = null,
    ?string $defaultTranslationText = null,
    ?Atlin $atlin = null
);

Translation Files

PHP

Return a plain associative array. Values can be strings or arrays of strings (for rnd()).

<?php
// langs/en/main.php
return [
    'title'   => 'Hello World',
    'greet'   => ['Hi!', 'Hey!', 'Hello!'],
];

Atlin

Standard key-value .atlin format:

@title
Hello Atlin World

@description
A lightweight localization library

API Reference

Locale

Lookup

Group Management

Fallback & 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

composer test

License

Licensed under the MIT License.