Derafu: Translation - Translation Library with Exception Support
A PHP library that solves one specific problem: making exceptions translatable without compromising your existing code, while providing powerful ICU message formatting support.
Features
- 🔄 Translatable Exceptions: Make any exception translatable with minimal changes.
- 🌍 ICU Support: Built-in ICU message formatting for complex messages.
- 📦 Multiple Formats: Load translations from PHP, JSON, YAML files or custom provider.
- ⛓️ Locale Fallback: Configurable locale fallback chain.
- 🎯 Framework Agnostic: Works with any system implementing Symfony’s TranslatorInterface.
- 🪶 Lightweight: Minimal dependencies (only requires
symfony/translation-contracts
). - 🧩 Extensible: Easy to add custom message providers.
Installation
composer require derafu/translation
Basic Usage
Making Exceptions Translatable
// Before: Your existing exception.
class ValidationException extends Exception
{
public function __construct(string $message)
{
parent::__construct($message);
}
}
// After: Just change the parent class.
class ValidationException extends TranslatableException
{
// No changes needed!
}
Using Translatable Exceptions
// 1. Simple string (works like before).
throw new ValidationException('Email is invalid');
// 2. With translation key and parameters.
throw new ValidationException([
'validation.email.invalid',
'email' => '[email protected]'
]);
// 3. With ICU formatting.
throw new ValidationException(
'The email {email} is not valid',
['email' => '[email protected]']
);
// 4. With complex ICU patterns.
throw new ValidationException(
'{gender, select, female{She} male{He} other{They}} sent {count, plural, one{# message} other{# messages}}',
[
'gender' => 'female',
'count' => 5
]
);
Translation Files
Support for multiple formats:
// PHP arrays (fastest).
// translations/messages/en.php
return [
'welcome' => 'Welcome {name}!',
'messages' => '{count, plural, =0{No messages} one{# message} other{# messages}}'
];
// JSON.
// translations/messages/en.json
{
"welcome": "Welcome {name}!",
"messages": "{count, plural, =0{No messages} one{# message} other{# messages}}"
}
// YAML (requires symfony/yaml).
# translations/messages/en.yaml
welcome: 'Welcome {name}!'
messages: '{count, plural, =0{No messages} one{# message} other{# messages}}'
Setting Up the Translator
use Derafu\Translation\Translator;
use Derafu\Translation\Provider\PhpMessageProvider;
// Create provider.
$provider = new PhpMessageProvider(__DIR__ . '/translations');
// Create translator with fallback locales.
$translator = new Translator(
$provider,
'en', // Optional. Default `null` for Translator y 'en' for ICU.
['es_CL', 'es', 'en'] // Optional. Default are: 'en', 'en_US', 'es', 'es_CL'.
);
// Use in your exception handling.
try {
// Your code.
} catch (TranslatableException $e) {
// Get translation for current locale.
echo $e->trans($translator);
// Or specific locale.
echo $e->trans($translator, 'es');
}
Message Providers
The library includes three message providers:
PhpMessageProvider
: Uses PHP files returning arrays (fastest).JsonMessageProvider
: Uses JSON files.YamlMessageProvider
: Uses YAML files (requiressymfony/yaml
).
Key Benefits
- Zero Compromise: Keep your existing exception handling code.
- ICU Power: Full ICU message formatting support.
- Flexible Loading: Choose your preferred translation file format.
- Clean Separation: Error logic stays separate from presentation.
- Type Safe: Full PHP 8.3+ type safety.
When to Use This Library
This library is perfect when you:
- Need to internationalize exceptions without refactoring.
- Want ICU message formatting support.
- Need flexible translation file formats.
- Want to keep error handling and translation separate.
- Use exceptions for business logic validation.
License
This library is licensed under the MIT License. See the LICENSE
file for more details.