 |
VOOZH | about |
|
VOOZH | about |
The HasLocalePreference interface defines a contract for entities that maintain their own locale preferences. This interface enables per-entity localization, allowing different users, customers, or models to receive translated content in their preferred language rather than the application's global locale.
This document covers the interface definition, integration patterns with the Translator class, and implementation strategies for entities that require locale preferences. For information about the core Translator contract, see Translator Contract. For details on global locale management within the translation system, see Core Translation System.
The HasLocalePreference interface is defined in src/Contracts/HasLocalePreference.php7-13 and consists of a single method:
| Method | Return Type | Description |
|---|---|---|
preferredLocale() | ?string | Returns the entity's preferred locale code (e.g., 'en', 'es', 'fr-CA') or null if no preference is set |
The nullable return type allows entities to indicate they have no explicit preference, deferring to the application's default locale resolution behavior.
Sources: src/Contracts/HasLocalePreference.php1-14
Diagram: Interface Implementation Pattern
This diagram illustrates how different entity types implement the HasLocalePreference interface. Each implementing class provides its own logic for determining the preferred locale based on its internal state or database fields.
Sources: src/Contracts/HasLocalePreference.php7-13
The HasLocalePreference interface integrates with the translation system by providing entity-aware locale resolution. When the Translator processes translations for operations involving entities, it can check if the entity implements this interface and use the returned locale preference.
Diagram: Locale Resolution Flow with HasLocalePreference
This diagram shows the decision tree for determining which locale to use when translating content. The entity's preferredLocale() takes precedence over context and fallback locales when available.
Sources: src/Contracts/HasLocalePreference.php7-13
A typical implementation stores the locale preference in a database column:
More complex implementations may compute the preference based on multiple factors:
Entities may inherit preferences from parent entities:
Sources: src/Contracts/HasLocalePreference.php7-13
| Strategy | Use Case | Return Behavior | Example |
|---|---|---|---|
| Direct Field | Single locale column | Returns field value or null | User model with locale column |
| Computed | Multiple factors determine locale | Returns calculated locale or null | Customer with country-based fallback |
| Hierarchical | Inherit from parent entity | Returns own preference or delegates to parent | Team member inheriting from team |
| Dynamic | External service determines locale | Returns value from external source | User preferences from separate service |
| Null Return | No preference set | Always returns null | Entities that defer to global locale |
The primary use case is providing personalized translations based on user preferences:
Different tenants or organizations may require different default locales:
When sending emails or notifications, the system can use the recipient's preferred locale:
Sources: src/Contracts/HasLocalePreference.php7-13
Diagram: Code Entity Relationships
This diagram maps the interface definition to its implementation classes and integration points within the translation system.
Sources: src/Contracts/HasLocalePreference.php1-14
The HasLocalePreference interface provides entity-level locale preferences, which differs from the request-level locale stored in Hyperf's context:
| Aspect | HasLocalePreference | Context Locale |
|---|---|---|
| Scope | Per-entity (user, customer, etc.) | Per-request/coroutine |
| Storage | Entity property/database | Hyperf Context (Context::get('locale')) |
| Lifetime | Persistent across requests | Request-scoped |
| Use Case | User preferences, personalization | Request language negotiation |
| Priority | Takes precedence when entity provided | Fallback when no entity preference |
| Accessed Via | $entity->preferredLocale() | $translator->getLocale() |
Diagram: Entity Preference vs Context Locale
This sequence diagram shows how entity-level locale preferences take precedence over context-stored locales when explicitly provided to translation methods.
Sources: src/Contracts/HasLocalePreference.php7-13
The HasLocalePreference interface is located in the contracts namespace:
Hypervel\Translation\Contracts\HasLocalePreference
File path: src/Contracts/HasLocalePreference.php5
This placement alongside other contracts (Translator Contract, Loader Contract) establishes it as a core architectural boundary in the translation system.
Always return valid locale codes or null. Invalid locale codes may cause translation failures:
Cache computed locale preferences to avoid repeated calculations:
Return null to explicitly indicate "no preference" rather than returning a default locale. This allows the translation system to apply its own fallback logic:
Sources: src/Contracts/HasLocalePreference.php7-13
The HasLocalePreference interface provides a lightweight, flexible contract for entity-level locale preferences within the translation system. Key characteristics:
preferredLocale() returns ?stringnull indicates no preference, allowing fallback to context/default localeTranslator to resolve locale before translationThe interface enables sophisticated multi-locale applications where different entities require different translation preferences without coupling entity logic to the translation system internals.
Refresh this wiki