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

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:

Current locale group (lazy-loaded from disk)
Fallback Localizer (if provided), recursively
Fallback string (if provided instead of a Localizer)
defaultTranslationText (constructor parameter / setter)
null

Running Tests

composer test

License

Licensed under the MIT License.

nabeghe/light-localization

包简介

关键字：

README 文档