Localization

Purpose and Scope

This page documents the localization system in hypervel/support, which provides multi-language support through translation files, pluralization, and locale management. The system uses the Lang facade to access translation services, load language files, and manage locales across the application.

For view-level rendering and templating, see Views and Blade Templating. For URL generation with locale support, see URL Generation.

---

Translation System Architecture

The localization system consists of several cooperating components that manage translation loading, retrieval, and pluralization.

Sources: src/Facades/Lang.php1-49

---

The Lang Facade

The Lang facade provides static access to the translation system. It resolves to the TranslatorContract interface, which is implemented by the Translator class.

Method Category	Key Methods	Purpose
Retrieval	get(), trans()	Retrieve translated strings with replacements
Pluralization	choice(), transChoice()	Handle pluralized translations
Existence	has(), hasForLocale()	Check if translation keys exist
Locale Management	getLocale(), setLocale(), getFallback()	Manage current and fallback locales
Loading	load(), addLines(), addJsonPath()	Load and register translations
Namespacing	addNamespace(), addPath()	Register package translation namespaces

Sources: src/Facades/Lang.php9-39

---

Translation File Structure

Translation files are organized hierarchically by namespace, group, and locale. The system supports both PHP array files and JSON key-value files.

PHP Translation Files

PHP translation files return associative arrays with nested structures:

resources/lang/
├── en/
│ ├── messages.php # group: messages, locale: en
│ ├── validation.php # group: validation, locale: en
│ └── auth.php # group: auth, locale: en
├── es/
│ ├── messages.php # group: messages, locale: es
│ └── validation.php # group: validation, locale: es
└── vendor/
 └── package-name/
 └── en/
 └── messages.php # namespace: package-name

JSON Translation Files

JSON files provide simple key-value translations for quick lookups:

resources/lang/
├── en.json # {"Welcome": "Welcome"}
└── es.json # {"Welcome": "Bienvenido"}

Sources: src/Facades/Lang.php15-19

---

Translation Keys and Parsing

Translation keys use dot notation to reference nested translations, with optional namespace prefixes.

Key Format

Format	Example	Description
Simple	welcome	Top-level key in default namespace
Nested	messages.welcome	Group and key
Deep Nested	messages.greetings.morning	Multi-level nesting
Namespaced	package::messages.welcome	Package namespace
JSON	Welcome	Direct JSON translation key

Key Parsing Process

The parseKey() method splits keys into three components: namespace, group, and item. The default namespace is * for application translations.

Sources: src/Facades/Lang.php20

---

Retrieving Translations

The primary method for retrieving translations is Lang::get(), which supports parameter replacement and locale fallback.

Basic Retrieval

Parameter Replacement

Translation strings support placeholder replacement using :parameter syntax:

Translation Resolution Flow

Sources: src/Facades/Lang.php10-12

---

Pluralization

The localization system handles pluralization through the choice() method and MessageSelector class, which applies language-specific pluralization rules.

Pluralization Syntax

Translation strings use pipe-separated alternatives with optional range specifiers:

Pluralization Rules

MessageSelector Integration

The MessageSelector class interprets pluralization rules and selects the appropriate variant:

Method	Purpose
getSelector()	Retrieve the current MessageSelector instance
setSelector()	Replace the MessageSelector implementation

Sources: src/Facades/Lang.php13-23

---

Locale Management

The translation system maintains a current locale and fallback locale for translation resolution.

Locale Operations

Locale Methods

Method	Description	Example
locale() / getLocale()	Get the current locale	Lang::getLocale() → 'en'
setLocale(string $locale)	Set the current locale	Lang::setLocale('es')
getFallback()	Get the fallback locale	Lang::getFallback() → 'en'
setFallback(string $fallback)	Set the fallback locale	Lang::setFallback('en')

Dynamic Locale Detection

The system supports custom locale detection logic through determineLocalesUsing():

Sources: src/Facades/Lang.php21-29

---

Namespace System for Package Translations

The namespace system allows packages to register their own translation directories without conflicting with application translations.

Namespace Registration

Namespace Methods

Method	Purpose	Usage
addNamespace(string $namespace, string $hint)	Register package translation directory	Lang::addNamespace('admin', base_path('packages/admin/lang'))
addPath(string $path)	Add additional translation path	Lang::addPath('/custom/translations')
addJsonPath(string $path)	Add JSON translation directory	Lang::addJsonPath('/custom/json')

Sources: src/Facades/Lang.php17-19

---

Missing Key Handling

The translation system provides a mechanism to handle missing translation keys through custom callbacks.

Default Behavior

When a translation key is not found:

1. The system checks the current locale
2. Falls back to the fallback locale (if enabled)
3. Returns the key itself if still not found

Custom Missing Key Handler

The handleMissingKeysUsing() method allows registration of a custom callback:

Sources: src/Facades/Lang.php16

---

Programmatic Translation Management

The localization system supports adding translations at runtime without file modifications.

Runtime Translation Registration

The addLines() method registers translations in memory for a specific locale and namespace:

Manual Loading

The load() method explicitly loads a translation group:

Loaded Translation State

Method	Purpose
setLoaded(array $loaded)	Set the loaded translations array
setParsedKey(string $key, array $parsed)	Cache a parsed key
flushParsedKeys()	Clear the parsed key cache

Sources: src/Facades/Lang.php14-35

---

View Integration

The View system integrates with translations through Blade directives and view methods.

Blade Translation Directives

The View facade provides translation methods that integrate with the Lang facade:

• startTranslation(array $replacements = []) - Begin capturing translation content
• renderTranslation() - Render the captured content through the translator

Sources: src/Facades/View.php78-79 src/Facades/Lang.php32-33

---

Translation Aliases and Helper Functions

The Lang facade provides method aliases for convenience:

Primary Method	Alias	Purpose
get()	trans()	Retrieve translation
choice()	transChoice()	Pluralized translation

These aliases maintain compatibility with common Laravel conventions and provide shorter method names.

Sources: src/Facades/Lang.php32-33

---

Best Practices and Patterns

Translation Key Organization

Checking Translation Existence

Use has() or hasForLocale() to check if translations exist before retrieval:

Sources: src/Facades/Lang.php10-11

---

Macro Support

Like other components in the hypervel/support package, the Lang facade supports macros for extending functionality:

Method	Purpose
macro(string $name, callable|object $macro)	Register a custom macro
mixin(object $mixin, bool $replace = true)	Register multiple macros from an object
hasMacro(string $name)	Check if a macro is registered
flushMacros()	Clear all registered macros

Sources: src/Facades/Lang.php36-39