README

Internationalization and Localization Contracts for the Hierone Framework

This package provides a comprehensive set of contracts (interfaces and traits) for implementing internationalization (i18n) and localization (l10n) features in Hierone applications. The contracts define standard interfaces for translation services, locale-aware components, and translatable objects.

Features

TranslatorInterface: Core translation service contract with support for pluralization, context-aware translations, and locale management
LocaleAwareInterface: Contract for components that need locale management capabilities
TranslatableInterface: Contract for objects that can provide translatable content (models, exceptions, etc.)
TranslatorTrait: Trait providing default implementation for common translation patterns
Modern PHP 8.2+: Full type declarations, union types, and modern PHP features
PSR Compliant: Follows PHP-FIG standards and best practices

Installation

composer require hierone/recap-contracts

Basic Usage

Implementing a Translator

use Hierone\Contracts\Recap\TranslatorInterface;

class MyTranslator implements TranslatorInterface
{
    public function trans(string $key, array $parameters = [], ?string $locale = null): string
    {
        // Your translation implementation
    }
    
    public function transChoice(string $key, int|float|\Countable $number, array $parameters = [], ?string $locale = null): string
    {
        // Your pluralization implementation
    }
    
    // ... other required methods
}

Creating Locale-Aware Components

use Hierone\Contracts\Recap\LocaleAwareInterface;

class LocalizedFormatter implements LocaleAwareInterface
{
    private string $locale = 'en';
    
    public function getLocale(): string
    {
        return $this->locale;
    }
    
    public function setLocale(string $locale): static
    {
        $this->locale = $locale;
        return $this;
    }
    
    // ... other required methods
}

Making Objects Translatable

use Hierone\Contracts\Recap\{TranslatableInterface, TranslatorTrait};

class ValidationError implements TranslatableInterface
{
    use TranslatorTrait;
    
    public function __construct(string $field, string $rule)
    {
        $this->setTranslationKey("validation.{$rule}")
             ->setTranslationParameters(['field' => $field])
             ->setFallbackMessage("Validation failed for {$field}");
    }
}

// Usage
$error = new ValidationError('email', 'required');
$message = $error->translate($translator, 'es');

Contract Details

TranslatorInterface

The core translation service interface providing:

Basic Translation: trans(string $key, array $parameters = [], ?string $locale = null)
Pluralization: transChoice(string $key, int|float|\Countable $number, array $parameters = [], ?string $locale = null)
Context-Aware: transWithContext(string $context, string $key, array $parameters = [], ?string $locale = null)
Locale Management: getLocale(), setLocale(), getFallbackLocale(), setFallbackLocale()
Translation Checking: has(string $key, ?string $locale = null)
Batch Operations: addTranslations(array $translations, string $locale, ?string $namespace = null)

LocaleAwareInterface

Interface for components that manage locale settings:

Current Locale: getLocale(), setLocale(string $locale)
Locale Support: isLocaleSupported(string $locale), getSupportedLocales()
Default Locale: getDefaultLocale(), setDefaultLocale(string $locale)
Locale Reset: resetLocale()

TranslatableInterface

Interface for objects that can be translated:

Translation Data: getTranslationKey(), getTranslationParameters(), getTranslationDomain()
Translation: translate(TranslatorInterface $translator, ?string $locale = null)
Fallback: getFallbackMessage(), isTranslatable()
Fluent API: withTranslationParameters(array $parameters), withLocale(?string $locale)

TranslatorTrait

Provides default implementation for TranslatableInterface:

Property Management: Protected properties for translation key, parameters, domain, and fallback
Default Behavior: Sensible defaults for all interface methods
Immutability: with* methods return cloned instances
Fallback Handling: Automatic fallback to key or custom message when translation unavailable

Advanced Usage

Context-Aware Translations

// Disambiguate translations with context
$translator->transWithContext('button', 'save', [], 'en'); // "Save"
$translator->transWithContext('money', 'save', [], 'en');  // "Put aside"

Pluralization

// Handle plural forms based on count
$translator->transChoice('messages.items', 0);  // "no items"
$translator->transChoice('messages.items', 1);  // "1 item"
$translator->transChoice('messages.items', 5);  // "5 items"

Locale-Aware Components

$formatter = new LocalizedFormatter();
$formatter->setLocale('de');

if ($formatter->isLocaleSupported('de')) {
    $formatted = $formatter->format($data);
}

Complex Translatable Objects

class UserNotification implements TranslatableInterface
{
    use TranslatorTrait;
    
    public function __construct(string $type, array $data)
    {
        $this->setTranslationKey("notifications.{$type}")
             ->setTranslationParameters($data)
             ->setTranslationDomain('user')
             ->setFallbackMessage("You have a new {$type} notification");
    }
}

Integration

These contracts are designed to work seamlessly with:

Hierone Framework: Core framework components use these contracts
Translation Libraries: Implement these interfaces in your translation services
Third-Party Packages: Use as dependency contracts in your packages
Testing: Mock these interfaces for unit testing translation-dependent code

Requirements

PHP 8.2 or higher
Support for strict typing and modern PHP features

License

This package is open-sourced software licensed under the MIT license.

Part of the Hierone Framework - Modern PHP development with elegance and performance.

hierone / recap-contracts

Maintainers

Details