Light Localization

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
);

Parameter	Description
$path	Absolute path to the translations root directory
$locale	Active locale code
$fallback	Another Localizer to chain, or a plain string used as default
$defaultTranslationText	Returned when no translation is found anywhere in the chain
$atlin	Custom Atlin instance; created automatically if 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

Method	Description
getLocale(): string	Returns the current locale
setLocale(string $locale): void	Changes the locale and clears all loaded groups
getLastLocale(): ?string	Locale used in the most recent successful lookup

Lookup

Method	Description
get(string $key, string $group = 'main', bool $deep = true): ?string	Returns the translation for a key
rnd(string $key, string $group = 'main', bool $deep = true): ?string	Like get(), but picks a random item when the value is an array
has(string $key, string $group = 'main', bool $deep = true): bool	Checks whether a key exists

Group Management

Method	Description
load(string $group): bool	Loads a translation group from disk
refresh(): void	Reloads all currently loaded groups
reset(): void	Clears all loaded groups from memory
resetTranslation(string $group): bool	Removes a specific group from memory
hasTranslation(string $group): bool	Checks whether a group is loaded in memory
hasTranslationFile(string $group): bool	Checks whether a group file exists on disk

Fallback & Default Text

Method	Description
getFallback()	Returns the current fallback (Localizer or string)
setFallback(Localizer|string|null $fallback): void	Sets a new fallback
getDefaultTranslationText(): ?string	Returns the static default text
setDefaultTranslationText(?string $text): void	Sets the static 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.