Laratext Laravel Package

Getting Started

Install the package with composer require edulazaro/laratext, then publish the config file:

php artisan vendor:publish --tag="texts"

Configure API keys (OPENAI_API_KEY, GOOGLE_TRANSLATOR_API_KEY) in .env and define your supported languages in config/texts.php.

Start using immediately in Blade or PHP:

• @text('welcome.message', 'Welcome back, :name!') in views
• text('welcome.message', 'Welcome back, :name!', ['name' => $user->name]) in PHP

Keys are auto-converted to readable strings (e.g., pages.contact_us → "Contact Us"), so no pre-defined translation files are needed. Run php artisan laratext:scan --write once to bootstrap your lang/texts/*.php files.

Implementation Patterns

Use text()/@text() consistently for all translatable strings—avoid Laravel’s native __() to prevent fragmentation. The package aggregates all calls into language files under lang/texts/{lang}.php automatically.

Typical workflow:

1. Develop features with human-readable keys and source text (e.g., text('error.not_found', 'The resource was not found')).
2. Run php artisan laratext:scan --write to discover and translate missing keys.
3. Add new languages by updating 'languages' in config/texts.php, then re-run the scan.

For multi-language support, batch translation is enabled by default (supports translateMany in translators), reducing API calls and cost. Configure your default translator (OpenAITranslator or GoogleTranslator) and set language priorities in texts.php.

Blade optimizations: use @text in forms, buttons, and headings—placeholders (:count, :user) are preserved across translations automatically.

Gotchas and Tips

⚠️ Placeholder hygiene: Never hardcode values into text() defaults (e.g., text('greeting', 'Hello, John!')). Always use :placeholder syntax (text('greeting', 'Hello, :name!')) to ensure placeholders survive translation and remain translatable.

⚠️ Source-of-truth changes: If you update the default text for an existing key (e.g., change 'Welcome back!' → 'Welcome back, friend!'), translations for other languages won’t auto-update. Run php artisan laratext:scan --write --resync to fix this.

🔧 Custom translators: Implement TranslatorInterface and register in config/texts.php. Use php artisan make:translator to scaffold stubs. Prefer implementing translateMany() over pure translate() for batch efficiency (fewer API round-trips, lower cost).

🔍 Debugging missing translations: Check lang/texts/ structure—translations go into texts/{lang}.php arrays, not standard Laravel lang/{lang}/*.php. Verify default_locale matches your primary language key in texts.php.

🎯 Performance tip: For high-volume apps, rate-limit scanning in CI and avoid running --resync frequently. Use --dry and --diff options to preview changes before committing language files.