Last indexed: 7 February 2026 (1f36a2)

Contracts and Interfaces

Overview

The hypervel/translation package uses a contract-based architecture to define system boundaries and enable loose coupling. Three interfaces in src/Contracts/ establish the architectural boundaries:

Contract	Purpose
`Translator`	Translation retrieval, pluralization, and locale management
`Loader`	Translation data loading and path/namespace registration
`HasLocalePreference`	Entity-level locale preference declaration

Child Pages:

4.1 Translator Contract - Method signatures and Hyperf integration
4.2 Loader Contract - Loading methods and path resolution
4.3 HasLocalePreference Interface - Entity locale preferences

Related Pages:

2 Core Translation System - Translator implementation
5 Translation Data Loading - Loader implementations
6 Configuration and Dependency Injection - Contract-to-implementation bindings

Sources: src/Contracts/Translator.php1-32 src/Contracts/Loader.php1-36 src/Contracts/HasLocalePreference.php1-14

Contract Layer Architecture

The contract layer extends Hyperf's base translation contracts while adding Hypervel-specific functionality. This layered inheritance pattern ensures compatibility with the Hyperf framework while providing additional capabilities.

Contract Layer Architecture

Sources: src/Contracts/Translator.php1-32 src/Contracts/Loader.php1-36 src/Contracts/HasLocalePreference.php1-14

Contract Overview

The package defines three contracts that serve distinct architectural purposes:

Contract	File Path	Extends	Purpose
`Translator`	`src/Contracts/Translator.php`	`Hyperf\Contract\TranslatorInterface`	Defines translation retrieval, pluralization, and locale management methods
`Loader`	`src/Contracts/Loader.php`	`Hyperf\Contract\TranslatorLoaderInterface`	Defines translation data loading and path/namespace registration
`HasLocalePreference`	`src/Contracts/HasLocalePreference.php`	None	Enables domain entities to declare preferred locales

Translator Contract

The Translator contract src/Contracts/Translator.php10 extends Hyperf's TranslatorInterface and declares four core methods:

get(string $key, array $replace = [], ?string $locale = null): mixed src/Contracts/Translator.php15 - Retrieves translated text for a given key
choice(string $key, array|Countable|float|int $number, array $replace = [], ?string $locale = null): string src/Contracts/Translator.php20 - Performs pluralization-aware translation
getLocale(): string src/Contracts/Translator.php25 - Returns the current active locale
setLocale(string $locale): void src/Contracts/Translator.php30 - Sets the active locale

See Translator Contract for detailed method documentation and usage examples.

Sources: src/Contracts/Translator.php1-32

Loader Contract

The Loader contract src/Contracts/Loader.php9 extends Hyperf's TranslatorLoaderInterface and declares five methods for managing translation data sources:

load(string $locale, string $group, ?string $namespace = null): array src/Contracts/Loader.php14 - Loads translations for a specific locale and group
addNamespace(string $namespace, string $hint): void src/Contracts/Loader.php19 - Registers a namespace with a path hint
addJsonPath(string $path): void src/Contracts/Loader.php24 - Adds a JSON translation directory
addPath(string $path): void src/Contracts/Loader.php29 - Adds a PHP translation directory
namespaces(): array src/Contracts/Loader.php34 - Returns all registered namespaces

See Loader Contract for detailed method documentation and path resolution behavior.

Sources: src/Contracts/Loader.php1-36

HasLocalePreference Interface

The HasLocalePreference interface src/Contracts/HasLocalePreference.php7 is a single-method contract that domain entities implement to provide locale preferences:

preferredLocale(): ?string src/Contracts/HasLocalePreference.php12 - Returns the entity's preferred locale or null if none

This contract enables user-specific or context-specific locale selection. See HasLocalePreference Interface for integration examples.

Sources: src/Contracts/HasLocalePreference.php1-14

Dependency Injection and Contract Resolution

The contract layer integrates with Hyperf's dependency injection container through factory mappings defined in ConfigProvider. The following diagram illustrates how abstract contracts resolve to concrete implementations at runtime:

Dependency Resolution Flow

The ConfigProvider::__invoke() method registers contract-to-factory mappings in the dependencies array. When application code requests Contracts\Translator, the container invokes TranslatorFactory::__invoke(), which requests Contracts\Loader, triggering LoaderFactory::__invoke(). This factory pattern enables lazy instantiation and environment-specific implementations.

Sources: src/ConfigProvider.php18-25 src/TranslatorFactory.php1-40 src/LoaderFactory.php1-30

Contract-Implementation Mapping

The following table maps contracts to their concrete implementations:

Contract	Primary Implementation	Alternative Implementation	Source Files
`Translator`	`Hypervel\Translation\Translator`	None	src/Translator.php
`Loader`	`Hypervel\Translation\FileLoader`	`Hypervel\Translation\ArrayLoader`	src/FileLoader.php src/ArrayLoader.php
`HasLocalePreference`	Application-defined entities	N/A	Application code (e.g., User model)

Loader Implementations

The Loader contract src/Contracts/Loader.php9 has two implementations:

Implementation	Use Case	Key Methods
`FileLoader` src/FileLoader.php	Production - reads from filesystem	`load()`, `loadPath()`, `loadNamespaced()`, `loadJsonPaths()`
`ArrayLoader` src/ArrayLoader.php	Testing - stores in memory	`load()`, `addMessages()`, `addJsonMessages()`

Loader Contract Implementations

The default configuration uses FileLoader via LoaderFactory::__invoke() src/LoaderFactory.php20-28 Applications can substitute ArrayLoader by overriding the container binding. See 5.1 File-Based Loading and 5.2 Memory-Based Loading for implementation details.

Sources: src/Contracts/Loader.php9-35 src/FileLoader.php1-200 src/ArrayLoader.php1-100

Design Principles

The contract layer follows SOLID principles:

Principle	Application
Single Responsibility	`Translator` handles translation retrieval; `Loader` handles data loading
Open/Closed	New implementations can be created without modifying contracts
Liskov Substitution	`FileLoader` and `ArrayLoader` are interchangeable via `Loader` contract
Interface Segregation	`HasLocalePreference` declares only `preferredLocale()` method
Dependency Inversion	`Translator` depends on `Loader` abstraction, not concrete classes

The Translator class src/Translator.php40-42 type-hints Loader contract, not FileLoader or ArrayLoader. This enables swapping implementations via DI configuration without code changes.

Sources: src/Translator.php40-42 src/Contracts/Loader.php9 src/Contracts/HasLocalePreference.php7

Extension Points

The contract layer provides three primary extension points for applications:

Custom Loader Implementation

Applications can implement custom Loader classes to load translations from databases, APIs, or other sources:

Custom Loader Examples

Custom loaders must implement load(), addNamespace(), addJsonPath(), addPath(), and namespaces() methods src/Contracts/Loader.php14-34

Sources: src/Contracts/Loader.php9-35

Entity Locale Preferences

Domain models implement HasLocalePreference src/Contracts/HasLocalePreference.php7 to provide user-specific or context-specific locales. The Translator::get() method checks for this interface when determining the active locale. See 4.3 HasLocalePreference Interface for implementation patterns.

Sources: src/Contracts/HasLocalePreference.php7-13

Translator Customization

Applications can extend the Translator class src/Translator.php21 or create alternative implementations of Contracts\Translator src/Contracts/Translator.php10 Override TranslatorFactory::__invoke() src/TranslatorFactory.php20 to return custom instances. See 6 Configuration and Dependency Injection for factory customization.

Sources: src/Contracts/Translator.php10 src/TranslatorFactory.php20-38

URL: https://deepwiki.com/hypervel/translation/4-contracts-and-interfaces