Translator Contract

Purpose and Scope

The Translator contract defines the public interface for translation services in the hypervel/translation package. This interface establishes the contract that all translator implementations must fulfill, enabling dependency injection, testability, and framework compatibility. It extends Hyperf's TranslatorInterface while adding translation-specific methods for pluralization and locale management.

For information about the concrete implementation of this contract, see Core Translation System. For details on the other contracts in the system, see Contracts and Interfaces.

Sources: src/Contracts/Translator.php1-31

---

Interface Definition

The Translator contract is defined in the Hypervel\Translation\Contracts namespace and serves as the primary abstraction for all translation operations. By depending on this interface rather than concrete implementations, application code remains decoupled from implementation details.

Diagram: Translator Contract Hierarchy

The contract extends Hyperf\Contract\TranslatorInterface to ensure compatibility with the Hyperf framework's service container and middleware systems, while adding translation-specific functionality.

Sources: src/Contracts/Translator.php5-10

---

Contract Methods

Overview Table

Method	Parameters	Return Type	Purpose
get()	string $key, array $replace = [], ?string $locale = null	mixed	Retrieve a translation by key with placeholder replacement
choice()	string $key, array|Countable|float|int $number, array $replace = [], ?string $locale = null	string	Get pluralized translation based on numeric value
getLocale()	None	string	Retrieve the current locale setting
setLocale()	string $locale	void	Change the active locale

Sources: src/Contracts/Translator.php12-31

---

Method: get()

The get() method is the primary translation retrieval mechanism. It resolves translation keys using dot notation and performs placeholder replacement.

Parameters

Parameter	Type	Required	Description
$key	string	Yes	Translation key in dot notation (e.g., messages.welcome, package::errors.not_found)
$replace	array	No	Associative array of placeholder replacements (:key => value)
$locale	?string	No	Override locale for this request; uses current locale if null

Return Value

Returns mixed to accommodate different translation formats:

• string for simple translations
• array for nested translation groups
• Original key if translation not found

Key Resolution Patterns

Diagram: Translation Key Resolution Flow

Sources: src/Contracts/Translator.php12-15

---

Method: choice()

The choice() method handles pluralization by selecting the appropriate translation form based on a numeric value. This method delegates to MessageSelector to apply locale-specific pluralization rules.

Parameters

Parameter	Type	Required	Description
$key	string	Yes	Translation key containing pipe-separated plural forms
$number	array|Countable|float|int	Yes	Numeric value or countable object determining plural form
$replace	array	No	Placeholder replacements; :count is automatically added
$locale	?string	No	Override locale for this request

Number Type Handling

The method accepts multiple types for the $number parameter to provide flexibility:

Input Type	Extraction Logic	Example
int	Direct use	choice('items', 5) → count = 5
float	Direct use	choice('items', 3.5) → count = 3.5
array	count($number)	choice('items', $array) → count = array length
Countable	count($number)	choice('items', $collection) → count = collection size

Return Value

Always returns a string containing the selected plural form with placeholders replaced.

Sources: src/Contracts/Translator.php17-20

---

Method: getLocale()

Retrieves the currently active locale. In a Hyperf application, this typically reads from the request context, allowing different concurrent requests to maintain separate locale states.

Return Value

Returns the ISO locale code as a string (e.g., en, es, zh-CN).

Typical Usage

Sources: src/Contracts/Translator.php22-25

---

Method: setLocale()

Changes the active locale for subsequent translation operations. This method typically stores the locale in Hyperf's request context to maintain isolation between concurrent requests.

Parameters

Parameter	Type	Required	Description
$locale	string	Yes	ISO locale code to activate (e.g., en, fr, ja)

Concurrent Request Handling

Diagram: Locale Isolation in Concurrent Requests

Sources: src/Contracts/Translator.php27-30

---

Dependency Injection Usage

The Translator contract integrates with Hyperf's dependency injection container, allowing type-hinted resolution in constructors, methods, and controllers.

Diagram: Contract Resolution Through Dependency Injection

Type-Hinted Constructor Injection

Application classes declare dependencies on the Translator contract, not concrete implementations:

The container automatically resolves Translator::class to the configured implementation (typically Hypervel\Translation\Translator) via TranslatorFactory.

Sources: src/Contracts/Translator.php1-31

---

Contract Extensions

The Translator contract extends Hyperf\Contract\TranslatorInterface, inheriting any methods defined by the framework's base interface. This ensures compatibility with Hyperf's built-in translation features and middleware.

Diagram: Interface Inheritance Hierarchy

By extending the framework's base interface, the package maintains interoperability while adding enhanced translation functionality.

Sources: src/Contracts/Translator.php8-10

---

Testing with the Contract

The contract-based design enables easy mocking and testing without depending on file system access or real translation files.

Diagram: Contract-Based Testing Strategy

Test implementations can:

• Return hardcoded strings for specific keys
• Verify that translation methods are called with expected parameters
• Simulate missing translations to test fallback behavior
• Mock locale changes to test internationalization logic

For memory-based testing with real translation logic, see Memory-Based Loading.

Sources: src/Contracts/Translator.php1-31

---

Summary

The Translator contract provides a stable, testable interface for translation operations in the hypervel/translation package. Its four methods (get(), choice(), getLocale(), setLocale()) cover all essential translation needs while maintaining compatibility with the Hyperf framework through interface extension.

Key characteristics:

• Framework Integration: Extends Hyperf\Contract\TranslatorInterface for seamless Hyperf compatibility
• Type Safety: Provides strict method signatures with typed parameters and return values
• Flexibility: Supports multiple input types for pluralization and optional locale overrides
• Testability: Enables dependency injection and mock implementations
• Concurrency: Designed for per-request locale isolation in concurrent environments

Application code should always depend on this contract rather than concrete implementations to maintain loose coupling and enable flexible testing strategies.

Sources: src/Contracts/Translator.php1-31