## Getting Started

### Minimal Steps
1. **Installation**:
   ```bash
   composer require outhebox/laravel-translations
   php artisan vendor:publish --provider="Outhebox\LaravelTranslations\LaravelTranslationsServiceProvider" --tag="migrations"
   php artisan migrate

Publish the config file:

php artisan vendor:publish --provider="Outhebox\LaravelTranslations\LaravelTranslationsServiceProvider" --tag="config"

First Use Case: Access the UI at /translations (default route). The package provides a built-in admin panel for managing translations without writing a single line of code.
Key Files:
- config/laravel-translations.php: Configuration for locales, default locale, and UI settings.
- database/migrations/: Migration for the translations table (auto-created).
- resources/views/vendor/laravel-translations/: Default UI templates (customizable).

Implementation Patterns

Core Workflows

Translation Management:
- Add/Edit/Delete: Use the UI to manage translations for any language. Supports nested keys (e.g., auth.login).
- Import/Export: Import from JSON/CSV or export to JSON/CSV via the UI. Example:
```
php artisan translations:export --locale=en --file=translations_en
```
- Grouping: Organize translations into logical groups (e.g., auth, validation) for better UI navigation.
Integration with Laravel:
- Language Switching: Use the trans helper or @lang Blade directive as usual. The package auto-loads translations from the database.
```
__('auth.login'); // Fetches from DB
```
- Fallback Locales: Configure fallback locales in config/laravel-translations.php:
```
'fallback_locales' => ['en'],
```
Customization:
- UI Templates: Override default views in resources/views/vendor/laravel-translations/.
- Middleware: Protect the /translations route with middleware (e.g., auth):
```
Route::middleware(['auth'])->group(function () {
    Route::get('/translations', [TranslationController::class, 'index']);
});
```
- Validation Rules: Extend validation logic by publishing the package’s validation rules:
```
php artisan vendor:publish --provider="Outhebox\LaravelTranslations\LaravelTranslationsServiceProvider" --tag="validation"
```

CLI Usage:

Bulk Operations: Use Artisan commands for bulk updates:

php artisan translations:update --locale=es --file=path/to/translations.json

Locale Management: Add/remove locales dynamically:
```
php artisan translations:add-locale --locale=ar
```

Gotchas and Tips

Pitfalls

Migration Conflicts:
- If you manually modify the translations table, run php artisan translations:table to regenerate the migration. Avoid altering the table structure directly.
Caching Issues:
- Clear the translation cache after manual DB updates:
```
php artisan translations:clear-cache
```
- Disable caching in config/laravel-translations.php for development:
```
'cache' => env('APP_ENV') !== 'local',
```
Nested Key Limitations:
- The UI may not handle deeply nested keys (e.g., user.profile.settings.notifications) intuitively. Flatten keys where possible or use dot notation consistently.
Permission Handling:
- The package does not include RBAC. Use Laravel’s built-in auth or packages like Spatie’s laravel-permission to restrict access to /translations.

Debugging Tips

Check Logs:
- Enable debug mode in config/laravel-translations.php:
```
'debug' => env('APP_DEBUG'),
```
- Logs appear in storage/logs/laravel.log.
Verify Locale Files:
- Ensure locale files (e.g., resources/lang/en/auth.php) are not conflicting with DB translations. The package prioritizes DB over files.
UI Glitches:
- Clear Vite cache if the UI fails to load:
```
npm run build
```
- Check for JavaScript errors in browser console (use browser-logs tool in Boost).

Extension Points

Custom Storage:

Override the storage engine by binding a custom TranslationRepository in a service provider:

$this->app->bind(
    \Outhebox\LaravelTranslations\Contracts\TranslationRepository::class,
    \App\Services\CustomTranslationRepository::class
);

Event Listeners:

Listen to translation events (e.g., TranslationCreated) for auditing or notifications:

use Outhebox\LaravelTranslations\Events\TranslationCreated;

TranslationCreated::listen(function ($event) {
    // Log or notify
});

API Endpoints:

Expose translation endpoints for headless use:

Route::get('/api/translations/{locale}', [TranslationController::class, 'getTranslations']);

Testing:

Mock the translation repository in tests:

$this->app->instance(
    \Outhebox\LaravelTranslations\Contracts\TranslationRepository::class,
    Mockery::mock(\Outhebox\LaravelTranslations\Contracts\TranslationRepository::class)
);

Test UI interactions with Pest:

it('updates a translation', function () {
    $this->actingAs(user())
         ->put('/translations/update', [
             'locale' => 'en',
             'key' => 'auth.login',
             'value' => 'Sign In',
         ])
         ->assertRedirect('/translations');
});

---

Laravel Translations Laravel Package