Language Laravel Package

Getting Started

Start by installing the package via Composer:

composer require joomla/language "~3.0"

The package is PHP 8.1+, requires the joomla/string package, and follows a traditional language-translation workflow. Create a Language instance with a base path and language code (e.g., en-GB), then use the Text class to translate keys. The simplest usage is:

use Joomla\Language\Language;  
use Joomla\Language\Text;  

$language = new Language('/path/to/app', 'en-GB');  
$text = new Text($language);  
echo $text->translate('COM_APP_HELLO');  

Language files live in /path/to/app/language/en-GB/en-GB.ini, and keys must match ^[A-Z][A-Z0-9_.\-]*$.

Implementation Patterns

• Service Provider Pattern: Use LanguageFactory (ideally via DI container) to manage reusable Language and Text instances. Configure defaults (base path, default language) through a registry-like config.
• Lazy Loading & Caching: LanguageFactory::getLanguage() caches instances per language—useful for multi-language apps or per-request reuse.
• Localization Extensions: Implement LocaliseInterface in xx-XX.localise.php to define language-specific behaviors (e.g., pluralization rules, transliteration). The factory auto-loads this when available.
• Inline Parameter Substitution: Use printf-style placeholders (%s, %d) in .ini files and pass parameters via Text::translate('KEY', ['arg']).
• DI Container Integration: Register LanguageFactoryProvider and inject Text/Language into services using Container. This is critical for testability and modern app structure.

Gotchas and Tips

• No Static Methods: v2 removed all static APIs (Text::_(), Language::getInstance() etc.). Always instantiate with proper dependencies—testing requires mocking Language + Text together.
• Uppercase Keys Only: Keys are normalized to uppercase during load and cataloguing—mixed-case keys in .ini files won’t match unless you extend MessageCatalogue. Debug with Language::debugFile() and check getErrorFiles().
• Explicit Base Path Required: Unlike v1, you must pass the language directory path (not JPATH_ROOT). For unit tests, mount a temporary directory with test .ini files.
• Removed Features: _QQ_ escape, Text::script(), and CMS-specific methods are gone. Re-implement JS string embedding or search helpers yourself.
• Plural Forms: Define pluralization via LocaliseInterface::getPluralSuffixes()—misconfiguring this breaks plural translations. Use en-GB\localise.php’s EnGBLocalise base class as a starting point for Western languages.
• Testing Tip: Mock Language and return stub MessageCatalogue instances; avoid loading real files in tests unless testing i18n loading itself.