Translator Laravel Package

Getting Started

Start by installing the package via Composer (composer require spiral/translator) and registering its service provider in your Spiral application. The core entry point is the Spiral\Translator\TranslatorInterface, which you can inject wherever translation is needed—typically in controllers, services, or view helpers. Begin with a basic usage: resolve a message by key and locale using $translator->translate('welcome.message', 'en_US'). For initial setup, examine the config/translator.php file (auto-generated if using Spiral skeleton), where you define message sources (e.g., arrays, YAML files per domain/ locale). A minimal first catalog might define messages.php per locale like messages/en.php.

Note (v1.3.1): The translator no longer throws an exception if a locale directory is missing—it silently falls back to the next available catalog. While this improves resilience, always validate the requested locale before calling translate() (e.g., via LocaleCatalog::hasLocale('en_US')) to avoid unintended fallback behavior in production.

Implementation Patterns

• Domain-Driven Translation: Organize messages by domains (e.g., auth, validation, errors) to isolate translation concerns. Use $translator->translate('login.submit', 'domain=auth') for clarity.
• Fallback & Default Locales: Configure default_locale and fallback_locale in config to gracefully handle missing translations. Implement a fallback chain (e.g., en_US → en) by defining locales as an array in config.
• Dynamic Translation: Inject TranslatorInterface into services (not controllers directly) to avoid tight coupling—e.g., build dynamic emails or notifications with localized body and subject.
• Integration with Views: Create a simple Blade-like helper (e.g., __() wrapper) that delegates to the translator—this keeps templates clean and testable.
• Testing: Mock TranslatorInterface in unit tests. Preload test catalogs in memory using ArrayCatalog for fast, deterministic tests. Since v1.3.1, your test setup should explicitly create expected locale directories or use ArrayCatalog to avoid silent fallbacks during test execution.

Gotchas and Tips

• Catalog Caching: Although lightweight, repeated file I/O can impact performance. Enable caching (via spiral/framework’s cache bridge or a custom CachedCatalogLoader) in production—especially for large message sets.
• Locale Normalization: The component expects normalized locale codes (e.g., en_US, not en-us). Always sanitize user-provided locale values before passing to translate() to avoid silent fallbacks or errors. v1.3.1 exacerbates this: missing directories now go unreported—so normalize and validate locales explicitly in middleware or validation layers.
• Missing Key Behavior: By default, it returns the key itself on missing translation—this helps during development but may leak raw keys in production if not caught in tests. Add an on_missing callback in config to log or replace with a placeholder (e.g., ?key?).
• Namespace Conflicts: Avoid using generic keys like title or error. Prefer namespaced keys (e.g., product.details.title) or explicit domains to prevent collisions across modules.
• Legacy Migration: If migrating from legacy strings, use the dump() method (if available in your version) to extract keys from codebase into YAML/PHP catalogs incrementally—start with a single domain (e.g., deprecated.php) and refactor over time.
• v1.3.1-Specific Tip: Since missing directories are no longer fatal, add integration tests that assert expected catalog paths exist (e.g., using Filesystem::exists() or glob() in tests/) to catch setup regressions early.