README

A lightweight, standalone internationalization module for PHP 8.1+ that integrates both PHP‑array and Gettext back‑ends with advanced locale fallback logic and PSR‑11 compatibility. Includes support for translatable enums and global translation helpers.

Installation

composer require seworqs/commons-i18n

Usage

use Seworqs\Commons\I18n\Factory\TranslatorFactory;
use Seworqs\Commons\I18n\Registry\TranslatorRegistry;

$translator = TranslatorFactory::createStandAlone([
    'locale' => 'nl_BE',
    'fallbackLocale' => 'en',
    'translation_file_patterns' => [
        ['type' => 'phpArray', 'base_dir' => 'path/to/language', 'pattern' => '%s.php'],
        ['type' => 'gettext', 'base_dir' => 'path/to/language', 'pattern' => '%s.mo'],
    ],
]);

TranslatorRegistry::register('default', $translator);

// Use helpers
use function Seworqs\Commons\I18n\t;
use function Seworqs\Commons\I18n\t2;
use function Seworqs\Commons\I18n\tc;

echo t('welcome.message');
echo t2('item.one', 'item.many', 5);
echo tc('errors', 'not_found');

Creating Your Own Translatable Enums

You can define your own enum like this:

use Seworqs\Commons\I18n\Contract\TranslatableEnumInterface;
use Seworqs\Commons\I18n\Traits\TranslatableEnumTrait;

enum Status: string implements TranslatableEnumInterface
{
    use TranslatableEnumTrait;

    case APPROVED = 'approved';
    case DECLINED = 'declined';

    public static function getTranslationPrefix(): string
    {
        return 'enum.status';
    }

    public static function getTextDomain(): string
    {
        return 'enum';
    }
}

Features

Combine multiple translation back-ends (PHP-array, Gettext) into a single composite translator
Implement region→language→final locale fallback (e.g. nl_BE → nl → en)
Provide standalone (createStandAlone) and PSR-11 (__invoke) translation factories
Include global helper functions (t(), t2(), tc()) for fast, in-code translations with placeholder and context support
Offer a centralized TranslatorRegistry with a sensible default key for global access
Load translations via configurable translation_file_patterns — PHP-array files or Gettext .mo files
Leverage PHP 8.1 modern features: constructor property promotion, readonly properties, strict types, and return declarations
Extensible architecture: add custom TranslatorInterface implementations or tweak fallback logic via decorators