Getting Started

Minimal Steps

Installation:
```
composer require rivalex/lingua
php artisan lingua:install
```
This publishes config, runs migrations, and seeds the database with your default language.
First Use Case:
- Access the UI at /lingua/languages to manage installed languages.
- Use the Add Language button to install a new locale (e.g., es for Spanish).
- Navigate to /lingua/translations to edit translations directly in the database.

Where to Look First

Configuration: config/lingua.php (customize default locale, sync behavior, UI settings).
Artisan Commands: Run php artisan lingua:update-lang to fetch the latest translations from laravel-lang.
UI Routes:
- /lingua/languages → Manage installed languages.
- /lingua/translations → Edit translations.
- /lingua/statistics → Track progress.

Implementation Patterns

Core Workflows

Database-Driven Translations:
- Use the Lingua Facade (Lingua::get('key', 'locale')) to fetch translations from the database.
- Example:
```
$translation = Lingua::get('auth.login', 'es'); // Returns Spanish translation
```
- Sync local files to the database:
```
php artisan lingua:sync-to-database
```

Language Management:

Add/remove languages via CLI:

php artisan lingua:add fr  # Add French
php artisan lingua:remove de # Remove German

Update all languages:
```
php artisan lingua:update-lang
```

Rich-Text Translations:
- Enable Markdown/HTML support in config/lingua.php under the editor key.
- Edit translations in the UI with a WYSIWYG editor (e.g., for help text or documentation).
Headless Language Selector:
- Use the @linguaSelector Blade component for a zero-CSS dropdown/modal/sidebar selector.
- Customize via config/lingua.php:
```
'selector' => [
    'mode' => 'dropdown', // 'sidebar' | 'modal' | 'dropdown'
    'show_flags' => true,
]
```
Vendor Translations:
- Manage package translations (e.g., vendor/laravel-lang) alongside your app’s translations.
- Sync vendor files to the database automatically during lingua:update-lang.

Integration Tips

Blade Integration: Use @lingua directive for translations:
```
<h1>@lingua('auth.welcome')</h1>
```
Fallback to default locale if missing:
```
<h1>@lingua('auth.welcome', fallback: true)</h1>
```

API Responses: Return translations dynamically:

return response()->json([
    'message' => Lingua::get('api.success', request()->locale),
]);

Middleware: Force a locale for specific routes:

Route::middleware(['locale' => 'es'])->group(function () {
    // Spanish-only routes
});

Testing: Mock translations in tests:

Lingua::shouldReceive('get')->andReturn('Mocked translation');

Gotchas and Tips

Pitfalls

Default Locale Lock:
- The default language (set in config/lingua.php) cannot be removed via the UI or CLI.
- Workaround: Temporarily change the default locale before removal.
Sync Conflicts:
- Manual edits to lang/ files may be overwritten during sync-to-database.
- Fix: Use sync-to-local to export database changes to files first.
Livewire Caching:
- Clear Livewire cache after major UI changes:
```
php artisan lingua:clear-cache
```
RTL Languages:
- Right-to-left (RTL) languages (e.g., Arabic) require additional CSS for alignment.
- Use the rtl class in your layout:
```
<html lang="{{ app()->getLocale() }}" class="{{ app()->isLocaleRTL() ? 'rtl' : '' }}">
```
Large Translation Sets:
- Database performance may degrade with >100K translations.
- Optimization: Add indexes to language_lines table (publish migrations first).

Debugging

Missing Translations:
- Check the Statistics page for missing keys.
- Use the Translations page filter: Show missing translations only.
Sync Issues:
- Verify file permissions for lang/ directory.
- Run php artisan lingua:sync-to-database --verbose for detailed logs.
UI Glitches:
- Clear browser cache or use ?flush=1 to bypass Livewire cache: /lingua/translations?flush=1.

Extension Points

Custom Fields:

Extend the language_lines table by publishing migrations:
```
php artisan vendor:publish --tag="lingua-migrations"
```

Add a notes column for translator comments:

Schema::table('language_lines', function (Blueprint $table) {
    $table->text('notes')->nullable();
});

Custom Validation:

Override translation validation in app/Providers/LinguaServiceProvider.php:

public function boot()
{
    Lingua::extend('validation', function ($validator, $key, $locale) {
        $validator->addRules([
            'key' => 'required|max:255',
            'value' => 'required|max:65535|custom:no_html_tags',
        ]);
    });
}

Custom UI Components:
- Publish and override Livewire views:
```
php artisan vendor:publish --tag="lingua-views"
```
- Example: Modify resources/views/vendor/lingua/livewire/translations.blade.php to add a custom column.

AI Translation Integration:

Hook into the lingua.translation.updated event to auto-translate via an API:

Lingua::listen('translation.updated', function ($translation) {
    if ($translation->locale !== 'en') {
        $translated = callToAITranslationAPI($translation);
        $translation->value = $translated;
        $translation->save();
    }
});

Configuration Quirks

Fallback Locale:
- Ensure config/lingua.php and config/app.php use the same fallback_locale.
- Example:
```
'fallback_locale' => 'en', // Must match app.fallback_locale
```

Editor Toolbar:

Disable unsafe HTML tags in the rich-text editor:

'editor' => [
    'allowed_tags' => ['<strong>', '<em>', '<p>'],
]

Database Drivers:
- For SQLite, ensure the lang_dir in config/lingua.php points to a writable directory.

Pro Tips

Bulk Updates:
- Use the Translations page bulk actions to update multiple keys at once.
Translation Groups:
- Organize keys by group (e.g., auth, validation) for easier filtering.

Localization Testing:

Switch locales dynamically in tests:

$this->actingAs(User::factory()->create())
     ->withSession(['locale' => 'fr']);

Deployment Workflow:

Sync to local before deployment:

php artisan lingua:sync-to-local
git add lang/
git commit -m "Update translations"

Collaboration:
- Use the Statistics page to assign missing translations to team members via comments (custom field).

Lingua Laravel Package