API Reference

Complete reference documentation for the Derafu Translation library.

• Interfaces
  • TranslatableInterface
  • MessageProviderInterface
• Classes
  • TranslatableMessage
  • Translator
• Exceptions
  • TranslatableException
• Message Providers
  • AbstractMessageProvider
  • PhpMessageProvider
  • JsonMessageProvider
  • YamlMessageProvider
• Error Handling

Interfaces

TranslatableInterface

Extends Symfony’s TranslatorInterface and adds ICU support.

interface TranslatableInterface extends TranslatorInterface, Stringable
{
    /**
     * Converts the message to a string using ICU formatting.
     */
    public function __toString(): string;
}

MessageProviderInterface

Defines how translation messages are loaded.

interface MessageProviderInterface
{
    /**
     * Returns all messages for a given locale and domain.
     *
     * @param string $locale The locale to load messages for.
     * @param string $domain The translation domain.
     * @return array<string, string> Array of messages where key is the message id.
     */
    public function getMessages(string $locale, string $domain = 'messages'): array;

    /**
     * Returns all available locales for a given domain.
     *
     * @param string $domain The translation domain.
     * @return array<string> List of available locales.
     */
    public function getAvailableLocales(string $domain = 'messages'): array;
}

Classes

TranslatableMessage

Core message class that supports ICU formatting.

final class TranslatableMessage implements TranslatableInterface
{
    /**
     * @param string $message The message used for translation.
     * @param array<string, mixed> $parameters Parameters for translation.
     * @param string|null $domain The translation domain.
     * @param string $defaultLocale The locale for ICU formatting.
     */
    public function __construct(
        string $message,
        array $parameters = [],
        ?string $domain = null,
        string $defaultLocale = 'en'
    );

    /**
     * @throws RuntimeException When ICU formatting fails.
     */
    public function __toString(): string;

    public function trans(
        TranslatorInterface $translator,
        ?string $locale = null
    ): string;
}

Translator

Main translator implementation, using Symfony’s TranslatorTrait, with ICU and fallback support.

final class Translator implements TranslatorInterface
{
    /**
     * @param MessageProviderInterface $provider Provider of messages.
     * @param string|null $locale Default locale.
     * @param array|null $fallbackLocales Fallback locales chain.
     */
    public function __construct(
        MessageProviderInterface $provider,
        ?string $locale = null,
        ?array $fallbackLocales = null
    );

    /**
     * @throws IntlException When ICU formatting fails
     */
    public function trans(
        ?string $id,
        array $parameters = [],
        ?string $domain = null,
        ?string $locale = null
    ): string;
}

Exceptions

TranslatableException

Base exception class that supports translation.

abstract class TranslatableException extends Exception implements TranslatableInterface
{
    /**
     * @param string|array|TranslatableInterface $message The exception message:
     *   - string: Used as both message and translation key.
     *   - array: First element is message, rest are parameters.
     *   - TranslatableInterface: Used directly.
     * @param int $code The exception code.
     * @param Throwable|null $previous Previous exception.
     * @throws InvalidArgumentException When message array is invalid.
     */
    public function __construct(
        string|array|TranslatableInterface $message,
        int $code = 0,
        ?Throwable $previous = null
    );

    public function trans(
        TranslatorInterface $translator,
        ?string $locale = null
    ): string;
}

Message Providers

AbstractMessageProvider

Base class for file-based message providers.

abstract class AbstractMessageProvider implements MessageProviderInterface
{
    /**
     * @param string $directory Base directory for translation files.
     * @throws RuntimeException If directory doesn't exist.
     */
    public function __construct(
        protected readonly string $directory
    );

    /**
     * Returns the file extension without dot.
     */
    abstract protected function getFileExtension(): string;

    /**
     * Parses a file into messages array.
     *
     * @throws RuntimeException If file can't be parsed.
     */
    abstract protected function parseFile(string $file): array;
}

PhpMessageProvider

Loads translations from PHP files.

final class PhpMessageProvider extends AbstractMessageProvider
{
    /**
     * Expected file format:
     * <?php
     * return [
     *     'key' => 'value',
     * ];
     *
     * @throws RuntimeException If file doesn't return array.
     */
    protected function parseFile(string $file): array;
}

JsonMessageProvider

Loads translations from JSON files.

final class JsonMessageProvider extends AbstractMessageProvider
{
    /**
     * Expected file format:
     * {
     *     "key": "value"
     * }
     *
     * @throws RuntimeException If JSON is invalid.
     */
    protected function parseFile(string $file): array;
}

YamlMessageProvider

Loads translations from YAML files (requires symfony/yaml).

final class YamlMessageProvider extends AbstractMessageProvider
{
    /**
     * Expected file format:
     * key: value
     *
     * @throws RuntimeException If YAML is invalid.
     */
    protected function parseFile(string $file): array;
}

Error Handling

All exceptions extend from base PHP exceptions.

Common exceptions:

• TranslatableRuntimeException: General runtime errors.
• TranslatableInvalidArgumentException: Invalid input parameters.

---

Can’t extend Derafu Translation exceptions? Then use TranslatableExceptionTrait in your exceptions to get the translation capabilities.