README

A production-ready internationalization (i18n) component for PHP applications.

Installation

composer require hierone/recap

Quick Start

use Hierone\Component\Recap\Translator;
use Hierone\Component\Recap\Catalog\ArrayCatalog;
use Hierone\Component\Recap\Formatter\SimpleMessageFormatter;

// Set up the translator
$catalog = new ArrayCatalog();
$formatter = new SimpleMessageFormatter();
$translator = new Translator($catalog, $formatter, 'en');

// Add translations
$catalog->addTranslations([
    'welcome' => 'Welcome to our application!',
    'user.greeting' => 'Hello, :name!',
    'items.zero' => 'no items',
    'items.one' => 'one item', 
    'items.other' => ':count items'
], 'en');

// Use translations
echo $translator->trans('welcome');
echo $translator->trans('user.greeting', ['name' => 'John']);
echo $translator->transChoice('items', 0); // "no items"
echo $translator->transChoice('items', 1); // "one item"
echo $translator->transChoice('items', 5, ['count' => 5]); // "5 items"

Features

Translation Management: Store and retrieve translations with locale support
Parameter Substitution: Replace placeholders in messages with dynamic values
Pluralization: Proper plural forms for 30+ languages following Unicode CLDR
File Loading: Load translations from PHP arrays and JSON files
Multiple Locales: Support for multiple languages with fallback handling
High Performance: ~3μs per translation call, suitable for high-traffic applications

Loading Translations from Files

JSON Files

use Hierone\Component\Recap\Loader\JsonLoader;

$loader = new JsonLoader();
$translations = $loader->load('/path/to/translations.json', 'en');
$catalog->addTranslations($translations, 'en');

PHP Array Files

use Hierone\Component\Recap\Loader\PhpArrayLoader;

$loader = new PhpArrayLoader();
$translations = $loader->load('/path/to/translations.php', 'en');
$catalog->addTranslations($translations, 'en');

Pluralization

The component includes sophisticated pluralization rules for languages like:

English/German: one, other
French: one, other
Russian/Polish: one, few, many, other
Arabic: zero, one, two, few, many, other
Japanese/Chinese: other (no pluralization)

// Automatic pluralization based on locale
$translator->setLocale('ru'); // Russian
echo $translator->transChoice('books', 2); // Uses Russian plural rules

Advanced Usage

Context-aware Translations

echo $translator->transWithContext('navigation', 'home'); // navigation.home

Fallback Locales

$translator->setFallbackLocale('en'); // Fall back to English if key not found

Custom Message Formatters

use Hierone\Component\Recap\Formatter\MessageFormatterInterface;

class CustomFormatter implements MessageFormatterInterface 
{
    public function format(string $message, array $parameters, string $locale): string
    {
        // Custom formatting logic
    }
}

$translator = new Translator($catalog, new CustomFormatter());

Requirements

PHP 8.2+
hierone/recap-contracts ^1.0

License

Licensed under the MIT License. See LICENSE file for details.

hierone / recap

Maintainers

Details