Laravel Translation Loader

https://github.com/spatie/laravel-translation-loader
Admin
Laravel Translation Loader is a Laravel package that enables translations to be stored in the...
Tokens:17,975
Snippets:270
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Example Usage of getCacheKey

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Example showing the generated cache key format.

```php
$key = LanguageLine::getCacheKey('messages', 'en');
// Returns: 'spatie.translation-loader.messages.en'
```

--------------------------------

### Complete Configuration Example

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

The default configuration file structure for the translation loader.

```php
<?php

return [

    /*
     * Language lines will be fetched by these loaders. You can put any class here that implements
     * the Spatie\TranslationLoader\TranslationLoaders\TranslationLoader-interface.
     */
    'translation_loaders' => [
        Spatie\TranslationLoader\TranslationLoaders\Db::class,
    ],

    /*
     * This is the model used by the Db Translation loader. You can put any model here
     * that extends Spatie\TranslationLoader\LanguageLine.
     */
    'model' => Spatie\TranslationLoader\LanguageLine::class,

    /*
     * This is the translation manager which overrides the default Laravel `translation.loader`
     */
    'translation_manager' => Spatie\TranslationLoader\TranslationLoaderManager::class,

];
```

--------------------------------

### Usage Example for Translation Loading

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

Example showing how translations are accessed after the service provider is registered.

```php
// The service provider is registered automatically via auto-discovery
// No manual configuration needed in application code

// After registration, translations load from database automatically:
__('messages.welcome'); // Loads from database or file system
```

--------------------------------

### Load Translations Examples

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Examples demonstrating how the load method retrieves translations from files, databases, or vendor packages.

```php
// Usage is automatic via Laravel's translation system
// Load English messages group (file + database)
$translations = $loader->load('en', 'messages');
// Returns: ['welcome' => 'Welcome', ...] with database values merged in

// Load vendor package translations (file only, no custom loaders)
$packageTranslations = $loader->load('en', 'my-package', 'my-vendor-package');
// Returns: only file translations

// Load JSON translations
$jsonTranslations = $loader->load('en', '*');
// Returns: ['hello' => 'Hello', ...] from both files and database
```

--------------------------------

### Cache Key Examples

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

Examples of generated cache keys for different translation groups and locales.

```php
'spatie.translation-loader.messages.en'
'spatie.translation-loader.validation.nl'
'spatie.translation-loader.*.fr'
```

--------------------------------

### Implement graceful degradation in load method

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Handles QueryException to allow application startup when the database table is missing during initial installation.

```php
try {
    $fileTranslations = parent::load($locale, $group, $namespace);
    // ... load from custom providers
} catch (QueryException $exception) {
    $modelClass = config('translation-loader.model');
    $model = new $modelClass();
    
    if (is_a($model, LanguageLine::class) && !Schema::hasTable($model->getTable())) {
        // Table doesn't exist (first time setup), use file translations only
        return parent::load($locale, $group, $namespace);
    }
    
    // Table exists but query failed, propagate the exception
    throw $exception;
}
```

--------------------------------

### Example Usage of getTranslationsForGroup

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Examples showing how to retrieve translations for specific groups or JSON translations.

```php
// Fetch all validation translations for English
$enValidations = LanguageLine::getTranslationsForGroup('en', 'validation');
// Returns: ['required' => 'This field is required', 'email' => 'Must be valid email']

// Fetch JSON translations
$jsonTranslations = LanguageLine::getTranslationsForGroup('en', '*');
// Returns: ['hello' => 'Hello', 'goodbye' => 'Goodbye']
```

--------------------------------

### InvalidConfiguration Example Exception Message

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

A concrete example of the exception message generated for an invalid model class.

```text
You have configured an invalid class `App\Models\User`.A valid class extends Spatie\TranslationLoader\LanguageLine.
```

--------------------------------

### Validate Configuration During Installation

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

Verify that the configured model class correctly implements the expected base class to prevent runtime failures.

```php
// artisan.php or console service provider
use Spatie\TranslationLoader\Exceptions\InvalidConfiguration;

try {
    $modelClass = config('translation-loader.model');
    $model = new $modelClass();
    
    if (!$model instanceof \Spatie\TranslationLoader\LanguageLine) {
        throw InvalidConfiguration::invalidModel($modelClass);
    }
} catch (InvalidConfiguration $e) {
    $this->error($e->getMessage());
    return 1; // Fail installation
}
```

--------------------------------

### Install package via Composer

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Use this command to add the package to your Laravel project.

```bash
composer require spatie/laravel-translation-loader
```

--------------------------------

### Provides Method Usage

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

Example of how the provides method is used internally by Laravel.

```php
// This is called internally by Laravel to optimize loading
$provided = $provider->provides();
// Returns: ['translator', 'translation.loader']
```

--------------------------------

### Handle InvalidConfiguration Exception

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

Example of catching an InvalidConfiguration exception when the configured model does not extend LanguageLine.

```php
// In config/translation-loader.php
'model' => 'App\Models\InvalidModel',  // Does not extend LanguageLine

// When loading translations:
try {
    $loader = new Db();
    $translations = $loader->loadTranslations('en', 'messages');
} catch (InvalidConfiguration $e) {
    // Message: "You have configured an invalid class `App\Models\InvalidModel`.
    //           A valid class extends Spatie\TranslationLoader\LanguageLine."
}
```

--------------------------------

### Get Cache Key Method

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Method signature for generating a cache key.

```php
public static function getCacheKey(string $group, string $locale): string
```

--------------------------------

### Usage of getTranslationsForTranslationLoaders

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Example showing how the manager aggregates translations from multiple configured loader classes.

```php
// Internally used by load() method
// With config containing [Db::class, CustomYamlLoader::class]
$allTranslations = $manager->getTranslationsForTranslationLoaders('en', 'messages');
// Returns merged translations from both Db and CustomYamlLoader
```

--------------------------------

### Load Translations Usage

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Examples of loading translations for specific locales and groups, including handling invalid model configurations.

```php
$loader = new Db();

// Load validation messages for English
$enValidations = $loader->loadTranslations('en', 'validation');
// Returns: ['required' => 'This field is required', 'email' => 'Must be valid email', ...]

// Load Dutch messages
$nlMessages = $loader->loadTranslations('nl', 'messages');
// Returns: ['welcome' => 'Welkom', 'goodbye' => 'Tot ziens', ...]

// Load JSON translations
$jsonTrans = $loader->loadTranslations('en', '*');
// Returns: ['hello' => 'Hello', 'goodbye' => 'Goodbye']

// Invalid model throws exception
// config('translation-loader.model') = 'InvalidClass'
try {
    $loader->loadTranslations('en', 'messages');
} catch (InvalidConfiguration $e) {
    // Exception message: "You have configured an invalid class..."
}
```

--------------------------------

### Publish and run migrations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Publish the migration files and run them to create the necessary database table.

```bash
php artisan vendor:publish --provider="Spatie\TranslationLoader\TranslationServiceProvider" --tag="translation-loader-migrations"
php artisan migrate
```

--------------------------------

### Package Directory Structure

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Overview of the source code and configuration file layout.

```text
src/
├── Exceptions/
│   └── InvalidConfiguration.php
├── TranslationLoaders/
│   ├── TranslationLoader.php       (interface)
│   └── Db.php                      (implementation)
├── LanguageLine.php                (Eloquent model)
├── TranslationLoaderManager.php     (core loader)
└── TranslationServiceProvider.php   (bootstrap)

config/
└── translation-loader.php

database/
└── migrations/
    └── create_language_lines_table.php.stub
```

--------------------------------

### Run Database Migrations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

Execute migrations before attempting to load translations to avoid QueryException errors.

```bash
# Ensure database table exists
php artisan migrate

# Then load translations (won't trigger QueryException)
```

--------------------------------

### Boot Method Definition

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

The boot method signature for the LanguageLine model.

```php
public static function boot(): void
```

--------------------------------

### Configure Package Method

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

Method signature for configuring the package.

```php
public function configurePackage(Package $package): void
```

--------------------------------

### Implement Graceful Configuration Validation

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

Shows how to catch InvalidConfiguration exceptions to log errors and provide a fallback return value.

```php
use Spatie\TranslationLoader\Exceptions\InvalidConfiguration;

try {
    $loader = app(Spatie\TranslationLoader\TranslationLoaders\Db::class);
    $translations = $loader->loadTranslations('en', 'messages');
} catch (InvalidConfiguration $e) {
    \Log::error('Invalid translation configuration', [
        'exception' => $e,
        'message' => $e->getMessage(),
    ]);
    
    // Fall back to empty translations
    return [];
}
```

--------------------------------

### Publish configuration file

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Publish the package configuration file to customize loaders, models, and managers.

```bash
php artisan vendor:publish --provider="Spatie\TranslationLoader\TranslationServiceProvider" --tag="translation-loader-config"
```

--------------------------------

### Project File Structure

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/DELIVERABLES.md

Visual representation of the project directory layout and documentation files.

```text
/workspace/home/output/
├── INDEX.md                         ← Start here for navigation
├── PACKAGE-OVERVIEW.md              ← Package context and features
├── README.md                        ← Quick start guide
├── configuration.md                 ← All configuration options
├── types.md                         ← Type definitions and schemas
├── errors.md                        ← Exception handling reference
├── DELIVERABLES.md                  ← This file
├── SUMMARY.txt                      ← Executive summary
└── api-reference/
    ├── translation-service-provider.md
    ├── language-line.md
    ├── translation-loader-manager.md
    ├── translation-loader-interface.md
    └── db-loader.md
```

--------------------------------

### Use Type-Safe Configuration

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

Utilize class constants instead of strings in configuration files to prevent typos and improve IDE support.

```php
// config/translation-loader.php
use Spatie\TranslationLoader\LanguageLine;
use Spatie\TranslationLoader\TranslationLoaders\Db;

return [
    'translation_loaders' => [
        Db::class,  // Use ::class instead of string
    ],
    'model' => LanguageLine::class,  // Use ::class
    'translation_manager' => TranslationLoaderManager::class,
];
```

--------------------------------

### Boot Method Usage

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Note regarding the automatic invocation of the boot method by Eloquent.

```php
// Called automatically by Laravel's Eloquent during model instantiation
// No manual calls needed
```

--------------------------------

### Run tests with Composer

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Execute the test suite for the package using the composer test command.

```bash
composer test
```

--------------------------------

### Access configuration and services

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Retrieve configuration values or resolved services from the application container.

```php
// Get the configured translation manager class
$managerClass = config('translation-loader.translation_manager');

// Get the configured model class
$modelClass = config('translation-loader.model');

// Get configured loaders
$loaders = config('translation-loader.translation_loaders');

// Get the instantiated translation loader
$loader = app('translation.loader');

// Get the translator instance
$translator = app('translator');
```

--------------------------------

### Retrieve and validate the configured model class

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Demonstrates how the loader retrieves the model class from configuration and validates that it extends the required LanguageLine class.

```php
protected function getConfiguredModelClass(): string
```

```php
// config/translation-loader.php
'model' => Spatie	ranslationLoader\
LanguageLine::class,

$loader = new Db();
$modelClass = $loader->getConfiguredModelClass();
// Returns: 'Spatie\TranslationLoader\LanguageLine'

// With invalid model:
// config/translation-loader.php
'model' => 'App\Models\User',

try {
    $modelClass = $loader->getConfiguredModelClass();
} catch (InvalidConfiguration $e) {
    echo $e->getMessage();
    // "You have configured an invalid class `App\Models\User`.
    //  A valid class extends Spatie\TranslationLoader\LanguageLine."
}
```

--------------------------------

### Configuration file contents

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Default settings for the translation loaders, models, and managers.

```php
return [

    /*
     * Language lines will be fetched by these loaders. You can put any class here that implements
     * the Spatie\TranslationLoader\TranslationLoaders\TranslationLoader-interface.
     */
    'translation_loaders' => [
        Spatie\TranslationLoader\TranslationLoaders\Db::class,
    ],

    /*
     * This is the model used by the Db Translation loader. You can put any model here
     * that extends Spatie\TranslationLoader\LanguageLine.
     */
    'model' => Spatie\TranslationLoader\LanguageLine::class,

    /*
     * This is the translation manager that overrides the default Laravel `translation.loader`
     */
    'translation_manager' => Spatie\TranslationLoader\TranslationLoaderManager::class,

];
```

--------------------------------

### Configure Multiple Custom Loaders

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Define multiple loaders in order of priority. Database loaders take precedence over custom file or API loaders.

```php
'translation_loaders' => [
    // Database loader (highest priority)
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
    
    // Custom YAML loader
    App\TranslationLoaders\YamlLoader::class,
    
    // Custom API loader (lowest priority)
    App\TranslationLoaders\RemoteApiLoader::class,
],
```

--------------------------------

### Handle Configuration Errors

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/INDEX.md

Catch InvalidConfiguration exceptions when interacting with the database loader.

```php
try {
    $loader = app(Db::class);
    $translations = $loader->loadTranslations('en', 'messages');
} catch (InvalidConfiguration $e) {
    // Invalid model configuration
}
```

--------------------------------

### Create and Retrieve Translations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Demonstrates creating a translation entry and using standard Laravel translation functions.

```php
use Spatie	ranslationLoader

// Create translation
LanguageLine::create([
    'group' => 'messages',
    'key' => 'welcome',
    'text' => ['en' => 'Welcome', 'nl' => 'Welkom']
]);

// Use in application (no change from standard Laravel)
__('messages.welcome'); // "Welcome"

// Change locale
app()->setLocale('nl');
__('messages.welcome'); // "Welkom"
```

--------------------------------

### Configure Translation Loaders

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Register the Db loader in the configuration file, optionally combining it with other custom loaders.

```php
// config/translation-loader.php
'translation_loaders' => [
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
],
```

```php
'translation_loaders' => [
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
    App\TranslationLoaders\YamlLoader::class,
    App\TranslationLoaders\CsvLoader::class,
],
```

--------------------------------

### Configure Translation Loader

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

Configuration structure for the translation-loader.php file.

```php
[
    'translation_loaders' => [
        'Spatie\TranslationLoader\TranslationLoaders\Db',
        // ... other loaders
    ],
    'model' => 'Spatie\TranslationLoader\LanguageLine',
    'translation_manager' => 'Spatie\TranslationLoader\TranslationLoaderManager',
]
```

--------------------------------

### Implement a custom translation provider

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Create a class implementing the TranslationLoader interface to fetch translations from custom sources like YAML or CSV files.

```php
namespace Spatie\TranslationLoader\TranslationLoaders;

interface TranslationLoader
{
    /*
     * Returns all translations for the given locale and group.
     */
    public function loadTranslations(string $locale, string $group): array;
}
```

--------------------------------

### Configure translation loaders in config/translation-loader.php

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Use this to define translation loaders and conditionally include them based on environment variables.

```php
// config/translation-loader.php

'translation_loaders' => [
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
    
    // Conditionally load additional loaders based on environment
    ...( env('LOAD_API_TRANSLATIONS', false) ? 
        [App\TranslationLoaders\ApiLoader::class] : 
        []
    ),
],
```

--------------------------------

### Create a translation entry

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/README.md

Use the LanguageLine model to store translation strings in the database.

```php
use Spatie\TranslationLoader\LanguageLine;

LanguageLine::create([
    'group' => 'messages',
    'key' => 'welcome',
    'text' => [
        'en' => 'Welcome to our application',
        'nl' => 'Welkom in onze applicatie',
    ]
]);
```

--------------------------------

### load

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Loads translations for a given locale and group, merging file system and database sources.

```APIDOC
## load(string $locale, string $group, string|null $namespace = null): array

### Description
Loads translations for a given locale and group. It merges file-based translations with database translations, where database values take precedence.

### Parameters
- **$locale** (string) - Required - The locale code (e.g., 'en', 'nl').
- **$group** (string) - Required - The translation group (e.g., 'messages', 'validation', '*' for JSON).
- **$namespace** (string|null) - Optional - Package namespace for vendor translations.

### Return Value
- **array** - An associative array of translations.

### Throws
- **QueryException** - Thrown if a database error occurs and the `language_lines` table exists.
```

--------------------------------

### Exception Hierarchy Diagram

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

A visual representation of the exception classes used within the package.

```text
Exception (PHP built-in)
├── InvalidConfiguration
│   └── Thrown by: Db::getConfiguredModelClass()
│
└── QueryException (Illuminate\Database\QueryException)
    └── Thrown by: TranslationLoaderManager::load()
```

--------------------------------

### Provides Method Signature

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

Method signature for the provides method.

```php
public function provides(): array
```

--------------------------------

### Implement Database Translation Loader

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-interface.md

The built-in database loader implementation using the LanguageLine model.

```php
namespace Spatie\\TranslationLoader\\TranslationLoaders;

use Spatie\\TranslationLoader\\LanguageLine;

class Db implements TranslationLoader
{
    public function loadTranslations(string $locale, string $group): array
    {
        $model = $this->getConfiguredModelClass();
        return $model::getTranslationsForGroup($locale, $group);
    }
    
    protected function getConfiguredModelClass(): string
    {
        $modelClass = config('translation-loader.model');
        if (! is_a(new $modelClass(), LanguageLine::class)) {
            throw InvalidConfiguration::invalidModel($modelClass);
        }
        return $modelClass;
    }
}
```

--------------------------------

### Register Loader Method

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

Method signature for registering the translation loader.

```php
protected function registerLoader(): void
```

--------------------------------

### Access Configuration Values

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

Retrieves configuration settings using the Laravel config helper.

```php
// Get all loaders
$loaders = config('translation-loader.translation_loaders');

// Get model class
$modelClass = config('translation-loader.model');

// Get translation manager class
$managerClass = config('translation-loader.translation_manager');
```

--------------------------------

### Configure Custom Model

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Set the custom model class in the package configuration.

```php
'model' => App\Models\CustomLanguageLine::class,
```

--------------------------------

### Handle QueryException in TranslationLoaderManager

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

This snippet demonstrates how the loader catches database query exceptions and falls back to file-based translations if the database table is missing.

```php
// From TranslationLoaderManager::load()
try {
    $fileTranslations = parent::load($locale, $group, $namespace);
    $loaderTranslations = $this->getTranslationsForTranslationLoaders($locale, $group, $namespace);
    return array_replace_recursive($fileTranslations, $loaderTranslations);
} catch (QueryException $exception) {
    $modelClass = config('translation-loader.model');
    $model = new $modelClass();
    
    // If table doesn't exist (first-time setup), use files only
    if (is_a($model, LanguageLine::class) && !Schema::hasTable($model->getTable())) {
        return parent::load($locale, $group, $namespace);
    }
    
    // Table exists but query failed - re-throw
    throw $exception;
}
```

--------------------------------

### Validate Configuration on Deployment

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

Provides a pattern for validating the translation model configuration within a service provider or console command.

```php
// In a service provider or console command
if (function_exists('config')) {
    $modelClass = config('translation-loader.model');
    try {
        $model = new $modelClass();
        if (!$model instanceof \Spatie\TranslationLoader\LanguageLine) {
            throw InvalidConfiguration::invalidModel($modelClass);
        }
    } catch (InvalidConfiguration $e) {
        \Log::critical('Invalid translation model configuration', [
            'configured_class' => $modelClass,
            'error' => $e->getMessage(),
        ]);
    }
}
```

--------------------------------

### Translation Loader Integration

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Demonstrates how the translation loader integrates with Laravel's native translation system and configuration.

```php
// Application usage - no direct interaction needed
// Laravel's translation system uses this loader automatically

__('messages.welcome'); // Loads via TranslationLoaderManager::load()

app('translator')->get('validation.email'); // Loads via load() method

// In configuration:
// config/translation-loader.php
'translation_loaders' => [
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
],
'model' => Spatie\TranslationLoader\LanguageLine::class,
'translation_manager' => Spatie\TranslationLoader\TranslationLoaderManager::class,
```

--------------------------------

### Implement Custom YAML Translation Loader

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-interface.md

A custom loader implementation that parses YAML files from the resources directory.

```php
namespace App\\TranslationLoaders;

use Spatie\\TranslationLoader\\TranslationLoaders\\TranslationLoader;
use Symfony\\Component\\Yaml\\Yaml;

class YamlLoader implements TranslationLoader
{
    public function loadTranslations(string $locale, string $group): array
    {
        $path = resource_path("lang/{$locale}/{$group}.yaml");
        
        if (!file_exists($path)) {
            return [];
        }
        
        $content = file_get_contents($path);
        return Yaml::parse($content) ?? [];
    }
}
```

--------------------------------

### InvalidConfiguration Exception Message Format

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

The template used for the exception message when an invalid model class is provided.

```text
You have configured an invalid class `{$className}`.A valid class extends Spatie	TranslationLoader	LanguageLine.
```

--------------------------------

### Create Basic Translations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/README.md

Stores translations in the database using a group and key, which can then be retrieved using the standard Laravel __() helper.

```php
LanguageLine::create([
    'group' => 'messages',
    'key' => 'welcome',
    'text' => ['en' => 'Welcome', 'nl' => 'Welkom']
]);

__('messages.welcome'); // "Welcome"
```

--------------------------------

### Register translation.loader service

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

The package registers the translation loader as a singleton in the service container.

```php
// Registered by TranslationServiceProvider::registerLoader()
$this->app->singleton('translation.loader', function ($app) {
    $class = config('translation-loader.translation_manager');
    return new $class($app['files'], $app['path.lang']);
});
```

--------------------------------

### Configure Custom Manager

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Set the custom manager class in the package configuration.

```php
'translation_manager' => App\Loaders\CustomManager::class,
```

--------------------------------

### Create a translation in the database

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Use the LanguageLine model to persist translation strings with support for multiple locales.

```php
use Spatie\TranslationLoader\LanguageLine;

LanguageLine::create([
   'group' => 'validation',
   'key' => 'required',
   'text' => ['en' => 'This is a required field', 'nl' => 'Dit is een verplicht veld'],
]);
```

--------------------------------

### Register Translator Method

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

Method signature for registering the translator.

```php
protected function registerTranslator(): void
```

--------------------------------

### Create Nested Translations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/README.md

Stores translations under specific groups for organized key management.

```php
LanguageLine::create([
    'group' => 'validation',
    'key' => 'required',
    'text' => ['en' => 'This field is required']
]);

__('validation.required'); // "This field is required"
```

--------------------------------

### Define Cache Key Format

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

The cache key follows a specific string pattern based on the group and locale.

```text
spatie.translation-loader.{group}.{locale}
```

--------------------------------

### Handle Invalid Configuration Errors

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Catch InvalidConfiguration exceptions when the translation model is incorrectly configured.

```php
$loader = new Db();
try {
    $translations = $loader->loadTranslations('en', 'messages');
} catch (InvalidConfiguration $e) {
    // Handle configuration error
    \Log::error('Invalid translation model configured', [
        'exception' => $e,
    ]);
}
```

--------------------------------

### Translation Priority Logic

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Conceptual flow for resolving translation keys across database and file sources.

```php
// If exists in database: use database version
// Else if exists in resources/lang/en/messages.php: use file version
// Else if fallback locale has version: use fallback
// Else: return null or use Laravel's default behavior
```

--------------------------------

### Register translator service

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

The package registers the translator instance in the service container.

```php
// Registered by TranslationServiceProvider::registerTranslator()
$this->app->singleton('translator', function ($app) {
    $loader = $app['translation.loader'];
    $trans = new Translator($loader, $app->getLocale());
    $trans->setFallback($app->getFallbackLocale());
    return $trans;
});
```

--------------------------------

### Configure Translation Manager

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Sets the class responsible for managing translation loading. Custom managers must extend Spatie\TranslationLoader\TranslationLoaderManager.

```php
'translation_manager' => Spatie\TranslationLoader\TranslationLoaderManager::class,
```

```php
<?php

namespace App\Loaders;

use Spatie\TranslationLoader\TranslationLoaderManager;

class CustomTranslationLoaderManager extends TranslationLoaderManager
{
    public function load($locale, $group, $namespace = null): array
    {
        $translations = parent::load($locale, $group, $namespace);
        
        // Custom post-processing or filtering
        return $this->filterTranslations($translations);
    }
    
    protected function filterTranslations(array $translations): array
    {
        // Implement custom filtering logic
        return $translations;
    }
}
```

```php
// config/translation-loader.php
'translation_manager' => App\Loaders\CustomTranslationLoaderManager::class,
```

--------------------------------

### Extend LanguageLine Model

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Create a custom model by extending the base LanguageLine class.

```php
namespace App\Models;

use Spatie\TranslationLoader\LanguageLine;

class CustomLanguageLine extends LanguageLine
{
    // Add custom fields, methods, or override behavior
}
```

--------------------------------

### Implement Custom CSV Translation Loader

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-interface.md

A custom loader implementation that reads translation data from CSV files.

```php
namespace App\\TranslationLoaders;

use Spatie\\TranslationLoader\\TranslationLoaders\\TranslationLoader;

class CsvLoader implements TranslationLoader
{
    public function loadTranslations(string $locale, string $group): array
    {
        $path = storage_path("translations/{$locale}/{$group}.csv");
        
        if (!file_exists($path)) {
            return [];
        }
        
        $translations = [];
        $handle = fopen($path, 'r');
        
        while (($row = fgetcsv($handle)) !== false) {
            if (count($row) >= 2) {
                $translations[$row[0]] = $row[1];
            }
        }
        
        fclose($handle);
        return $translations;
    }
}
```

--------------------------------

### Custom Manager with Logging

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Extend the TranslationLoaderManager to add custom logging or performance tracking during the translation loading process.

```php
// config/translation-loader.php
'translation_manager' => App\Loaders\LoggingTranslationManager::class,

// app/Loaders/LoggingTranslationManager.php
<?php

namespace App\Loaders;

use Spatie\TranslationLoader\TranslationLoaderManager;
use Illuminate\Support\Facades\Log;

class LoggingTranslationManager extends TranslationLoaderManager
{
    public function load($locale, $group, $namespace = null): array
    {
        Log::info('Loading translations', [
            'locale' => $locale,
            'group' => $group,
            'namespace' => $namespace,
        ]);
        
        $start = microtime(true);
        $translations = parent::load($locale, $group, $namespace);
        $duration = microtime(true) - $start;
        
        Log::debug('Translation load completed', [
            'locale' => $locale,
            'group' => $group,
            'count' => count($translations),
            'duration_ms' => round($duration * 1000, 2),
        ]);
        
        return $translations;
    }
}
```

--------------------------------

### Retrieve translations via TranslationLoaderManager

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-interface.md

Demonstrates how the manager iterates through configured loaders and merges their results using the service container.

```php
// From TranslationLoaderManager::getTranslationsForTranslationLoaders()
collect(config('translation-loader.translation_loaders'))
    ->map(function (string $className) {
        return app($className);  // Service container instantiation
    })
    ->mapWithKeys(function (TranslationLoader $translationLoader) use ($locale, $group) {
        return $translationLoader->loadTranslations($locale, $group);
    })
    ->toArray();
```

--------------------------------

### Implement Remote API Translation Loader

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-interface.md

A custom loader implementation that fetches translations from an external API endpoint.

```php
namespace App\\TranslationLoaders;

use Spatie\\TranslationLoader\\TranslationLoaders\\TranslationLoader;
use Illuminate\\Support\\Facades\\Http;

class ApiLoader implements TranslationLoader
{
    public function loadTranslations(string $locale, string $group): array
    {
        try {
            $response = Http::get(config('services.translation_api.url'), [
                'locale' => $locale,
                'group' => $group,
            ]);
            
            return $response->json('translations', []);
        } catch (\\Exception $e) {
            report($e);
            return [];
        }
    }
}
```

--------------------------------

### Validate Translation Loader Configuration in Service Provider

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Use this service provider to verify that the configured model, loaders, and manager classes exist before the application proceeds. It includes checks to skip validation during migrations or testing.

```php
<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Spatie\TranslationLoader\Exceptions\InvalidConfiguration;

class TranslationConfigValidator extends ServiceProvider
{
    public function boot(): void
    {
        if ($this->app->runningInConsole() && !$this->isTestingOrMigration()) {
            return;
        }
        
        try {
            $this->validateConfiguration();
        } catch (InvalidConfiguration $e) {
            throw $e;
        }
    }
    
    private function validateConfiguration(): void
    {
        $modelClass = config('translation-loader.model');
        $loaders = config('translation-loader.translation_loaders');
        $manager = config('translation-loader.translation_manager');
        
        // Validate model
        try {
            new $modelClass();
        } catch (\Exception $e) {
            throw InvalidConfiguration::invalidModel($modelClass);
        }
        
        // Validate loaders
        foreach ($loaders as $loader) {
            if (!class_exists($loader)) {
                throw new InvalidConfiguration("Loader class {$loader} does not exist");
            }
        }
        
        // Validate manager
        if (!class_exists($manager)) {
            throw new InvalidConfiguration("Manager class {$manager} does not exist");
        }
    }
    
    private function isTestingOrMigration(): bool
    {
        return str_contains(implode(' ', $_SERVER['argv'] ?? []), [
            'migrate',
            'tinker',
            'test',
            'pest',
        ]);
    }
}
```

--------------------------------

### Custom Model with Additional Fields

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Extend the base LanguageLine model to add custom database fields and scopes.

```php
// config/translation-loader.php
'model' => App\Models\EnhancedLanguageLine::class,

// app/Models/EnhancedLanguageLine.php
<?php

namespace App\Models;

use Spatie\TranslationLoader\LanguageLine;

class EnhancedLanguageLine extends LanguageLine
{
    protected $fillable = ['group', 'key', 'text', 'category', 'reviewed'];
    
    // Add additional database columns
    // - category (for organizing translations)
    // - reviewed (boolean flag for QA)
    
    public function scopeReviewedOnly($query)
    {
        return $query->where('reviewed', true);
    }
}
```

--------------------------------

### Handle Non-Existent Model Class

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

Illustrates that referencing a non-existent class triggers a PHP Fatal Error before the library's validation logic can execute.

```php
// config/translation-loader.php
'model' => 'App\Models\NonExistentModel',

try {
    $loader = new Db();
    $translations = $loader->loadTranslations('en', 'messages');
} catch (Throwable $e) {
    // Will trigger PHP error (class not found) before InvalidConfiguration
    // The Db loader attempts instantiation: new $modelClass()
    // If class doesn't exist, PHP throws error first
}
```

--------------------------------

### Load Translations Programmatically

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/INDEX.md

Retrieve translations using the translation loader manager instance.

```php
$loader = app('translation.loader');
$translations = $loader->load('en', 'messages');
```

--------------------------------

### Create JSON translations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Uses the '*' group to store JSON-style translations that can be accessed without a group prefix.

```php
LanguageLine::create([
    'group' => '*',
    'key' => 'hello',
    'text' => ['en' => 'Hello', 'nl' => 'Hallo']
]);

// Accessible via:
__('hello'); // Returns: 'Hello'
```

--------------------------------

### Retrieve translations using Laravel helpers

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Translations are fetched using the standard __() helper, respecting the current application locale.

```php
__('validation.required'); // returns 'This is a required field'

app()->setLocale('nl');

__('validation.required'); // returns 'Dit is een verplicht veld'
```

--------------------------------

### Configure Translation Model

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Specifies the Eloquent model used for database storage. Custom models must extend Spatie\TranslationLoader\LanguageLine.

```php
'model' => Spatie\TranslationLoader\LanguageLine::class,
```

```php
'model' => App\Models\CustomLanguageLine::class,
```

```php
<?php

namespace App\Models;

use Spatie\TranslationLoader\LanguageLine;

class CustomLanguageLine extends LanguageLine
{
    // Override table name if needed
    protected $table = 'custom_language_lines';
    
    // Add custom methods or override parent methods
    public function getTranslation(string $locale): string|null
    {
        // Custom implementation
        return parent::getTranslation($locale);
    }
}
```

```php
// config/translation-loader.php
'model' => App\Models\CustomLanguageLine::class,
```

--------------------------------

### Configure Translation Loaders

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/configuration.md

Defines the array of classes responsible for loading translations. Later loaders in the array take precedence over earlier ones.

```php
'translation_loaders' => [
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
],
```

```php
'translation_loaders' => [
    Spatie\TranslationLoader\TranslationLoaders\Db::class,
    App\TranslationLoaders\YamlLoader::class,
    App\TranslationLoaders\CsvLoader::class,
],
```

--------------------------------

### Define Db Class

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Class definition for the Db translation loader.

```php
class Db implements TranslationLoader
```

--------------------------------

### InvalidConfiguration Exception Definition

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

The structure of the InvalidConfiguration exception class.

```php
class InvalidConfiguration extends Exception
{
    public static function invalidModel(string $className): self
}
```

--------------------------------

### Registering Custom Translation Loaders

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Custom loaders must implement the TranslationLoader interface and be registered in the configuration array.

```php
'translation_loaders' => [
    Db::class,
    Custom\YamlLoader::class,
    Custom\CsvLoader::class,
]
```

--------------------------------

### getCacheKey

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Generates a cache key for storing translations of a specific group and locale.

```APIDOC
## getCacheKey(string $group, string $locale)

### Description
Generates a cache key for storing translations of a specific group and locale in the format: spatie.translation-loader.{group}.{locale}.

### Parameters
- **$group** (string) - Required - The translation group
- **$locale** (string) - Required - The locale code

### Return Value
- **string** - The generated cache key.

### Example
```php
$key = LanguageLine::getCacheKey('messages', 'en');
```
```

--------------------------------

### Create a new translation

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Stores a new translation entry in the database, making it available via the standard Laravel translation helper.

```php
use Spatie\TranslationLoader\LanguageLine;

LanguageLine::create([
    'group' => 'validation',
    'key' => 'required',
    'text' => [
        'en' => 'This field is required',
        'nl' => 'Dit veld is verplicht'
    ]
]);

// Now accessible via Laravel's translation helper:
__('validation.required'); // Returns: 'This field is required' (in English)
```

--------------------------------

### Define getTranslationsForTranslationLoaders method signature

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

Method signature for retrieving translations from all configured loaders.

```php
protected function getTranslationsForTranslationLoaders(
    string $locale,
    string $group,
    string|null $namespace = null
): array
```

--------------------------------

### TranslationLoaderManager::load

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/README.md

Loads translations by merging all configured sources.

```APIDOC
## TranslationLoaderManager::load($locale, $group, $namespace = null)

### Description
Loads translations by merging results from all configured translation loaders.

### Parameters
- **locale** (mixed) - Required - The locale.
- **group** (mixed) - Required - The translation group.
- **namespace** (mixed) - Optional - The translation namespace.

### Returns
- **array** - The merged array of translations.
```

--------------------------------

### Class Definition

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-service-provider.md

The class definition for the TranslationServiceProvider.

```php
class TranslationServiceProvider extends PackageServiceProvider implements DeferrableProvider
```

--------------------------------

### Translation Data Flow Diagram

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/README.md

Visual representation of how translation requests are processed through the loader manager and merged with database sources.

```text
Application Code
    ↓
__('messages.welcome')
    ↓
Laravel Translator (app('translator'))
    ↓
TranslationLoaderManager::load($locale, $group)
    ↓
Parallel:
├─ Load file translations via parent FileLoader
└─ Load database translations via Db loader
    ↓
Merge with array_replace_recursive()
    ↓
Return merged translation array
    ↓
Translator returns specific key's value
    ↓
Return to application: "Welcome to our application"
```

--------------------------------

### Create language_lines table

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/INDEX.md

SQL schema definition for the language_lines table used to store translation data.

```sql
CREATE TABLE language_lines (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    group VARCHAR(255) NOT NULL,
    key VARCHAR(255) NOT NULL,
    text JSON NOT NULL,
    created_at TIMESTAMP NOT NULL,
    updated_at TIMESTAMP NOT NULL,
    INDEX(group)
);
```

--------------------------------

### Retrieve Translations for Group

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Method signature for fetching translations based on locale and group.

```php
public static function getTranslationsForGroup(string $locale, string $group): array
```

--------------------------------

### Retrieve translation strings

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Use the standard Laravel __() helper function to retrieve translations from the database.

```php
__('messages.welcome', ['name' => 'dayle']);
```

--------------------------------

### Define Multi-Locale Translations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Shows how to store multiple locale translations within the text JSON field.

```php
LanguageLine::create([
    'group' => 'greetings',
    'key' => 'hello',
    'text' => [
        'en' => 'Hello',
        'nl' => 'Hallo',
        'de' => 'Hallo',
        'fr' => 'Bonjour',
        'es' => 'Hola',
        'it' => 'Ciao',
        'pt' => 'Olá',
        'ja' => 'こんにちは',
        // ... unlimited locales
    ]
]);
```

--------------------------------

### Define LanguageLine Model

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

The class definition for the LanguageLine model extending the Eloquent Model.

```php
class LanguageLine extends Model
```

--------------------------------

### Configure Translation Loader Model

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Defines the model class used by the translation loader in the configuration file.

```php
'model' => Spatie\TranslationLoader\LanguageLine::class,
```

```php
// config/translation-loader.php
'model' => App\Models\CustomLanguageLine::class,
```

--------------------------------

### Define TranslationLoader Interface

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

Contract that all translation source implementations must implement.

```php
interface TranslationLoader
{
    public function loadTranslations(string $locale, string $group): array;
}
```

--------------------------------

### Load Translations Method Signature

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

The signature for the load method used to retrieve translations for a specific locale and group.

```php
public function load($locale, $group, $namespace = null): array
```

--------------------------------

### loadTranslations(string $locale, string $group)

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-interface.md

Loads all translations for a given locale and group from the custom source. This method is invoked by the TranslationLoaderManager when translations are requested.

```APIDOC
## loadTranslations

### Description
Loads all translations for a given locale and group from the custom source. The returned array is merged with other sources, with custom sources typically taking precedence over file-based translations.

### Method
public function loadTranslations(string $locale, string $group): array

### Parameters
- **$locale** (string) - Required - The locale code (e.g., 'en', 'nl', 'fr')
- **$group** (string) - Required - The translation group (e.g., 'messages', 'validation', '*' for JSON)

### Return Type
array

### Return Value Description
Associative array of translation keys and values. For regular groups, use dot notation keys (e.g., 'validation.required'). For JSON group ('*'), use flat keys (e.g., 'hello').
```

--------------------------------

### loadTranslations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/db-loader.md

Retrieves translations from the database for a specific locale and group.

```APIDOC
## loadTranslations(string $locale, string $group)

### Description
Loads all translations from the database for the given locale and group. It validates the configured model class and retrieves cached translations.

### Parameters
- **$locale** (string) - Required - The locale code (e.g., 'en', 'nl', 'fr')
- **$group** (string) - Required - The translation group (e.g., 'messages', 'validation', '*' for JSON)

### Return Value
- **array** - Associative array of translations. Returns a nested structure for regular groups and a flat structure for JSON groups ('*').

### Throws
- **InvalidConfiguration** - Thrown if the configured model class does not extend the LanguageLine model.

### Example
```php
$loader = new Db();
$enValidations = $loader->loadTranslations('en', 'validation');
```
```

--------------------------------

### Define Regular Group Translation Format

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

Represents translation groups using nested associative arrays or flat dot-notation keys.

```php
[
    'validation' => [
        'required' => 'This field is required',
        'email' => 'The email field must be valid',
        'unique' => 'The value has already been taken',
    ]
]
```

```php
[
    'validation.required' => 'This field is required',
    'validation.email' => 'The email field must be valid',
    'validation.unique' => 'The value has already been taken',
]
```

--------------------------------

### Retrieve translations with getTranslation

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Fetches a translation for a specific locale, falling back to the application's default locale if the requested one is missing.

```php
public function getTranslation(string $locale): string|null
```

```php
$line = LanguageLine::create([
    'group' => 'messages',
    'key' => 'welcome',
    'text' => ['en' => 'Welcome', 'nl' => 'Welkom']
]);

$line->getTranslation('en'); // Returns: 'Welcome'
$line->getTranslation('nl'); // Returns: 'Welkom'
$line->getTranslation('fr'); // Returns: 'Welcome' (fallback to app.fallback_locale)
$line->getTranslation('de'); // Returns: null (if no fallback text)
```

--------------------------------

### Replace Translation Service Provider

Source: https://github.com/spatie/laravel-translation-loader/blob/main/README.md

Swap the default Laravel translation service provider with the package's provider in your application configuration.

```php
Illuminate\Translation\TranslationServiceProvider::class,
```

```php
Spatie\TranslationLoader\TranslationServiceProvider::class,
```

--------------------------------

### setTranslation(string $locale, string $value)

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Sets the translated text for a specific locale, merging with existing translations.

```APIDOC
## setTranslation(string $locale, string $value)

### Description
Adds or updates a translation for the given locale in the text field, preserving existing translations for other locales. This method supports chaining and requires a subsequent call to save() to persist changes.

### Parameters
- **$locale** (string) - Required - The locale code to set.
- **$value** (string) - Required - The translation text.

### Return Value
- **static** - Returns the LanguageLine instance for method chaining.
```

--------------------------------

### Extend TranslationManager

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/PACKAGE-OVERVIEW.md

Override the loading logic by extending the TranslationLoaderManager.

```php
namespace App\Loaders;

use Spatie\TranslationLoader\TranslationLoaderManager;

class CustomManager extends TranslationLoaderManager
{
    public function load($locale, $group, $namespace = null): array
    {
        $translations = parent::load($locale, $group, $namespace);
        // Custom post-processing
        return $translations;
    }
}
```

--------------------------------

### Update existing translations

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Retrieves a specific translation line and updates its text for a given locale.

```php
$line = LanguageLine::where('group', 'messages')
    ->where('key', 'welcome')
    ->first();

$line->setTranslation('fr', 'Bienvenue')->save();
```

--------------------------------

### InvalidConfiguration invalidModel Method Signature

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/errors.md

The signature for the factory method used to generate the invalid model exception.

```php
public static function invalidModel(string $className): self
```

--------------------------------

### Set translations with setTranslation

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/language-line.md

Updates or adds a translation for a specific locale without overwriting existing ones. Requires a subsequent call to save() to persist changes.

```php
public function setTranslation(string $locale, string $value): static
```

```php
$line = LanguageLine::create([
    'group' => 'messages',
    'key' => 'welcome',
    'text' => ['en' => 'Welcome']
]);

$line->setTranslation('nl', 'Welkom')
    ->setTranslation('fr', 'Bienvenue')
    ->save();

// Now text contains: ['en' => 'Welcome', 'nl' => 'Welkom', 'fr' => 'Bienvenue']
```

--------------------------------

### Translation Merge Strategy

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/api-reference/translation-loader-manager.md

The system uses array_replace_recursive to merge file-based and database-based translations, where database entries take priority.

```php
return array_replace_recursive($fileTranslations, $loaderTranslations);
```

--------------------------------

### Define LanguageLine Model

Source: https://github.com/spatie/laravel-translation-loader/blob/main/_autodocs/types.md

The LanguageLine model uses the translatable trait and casts the text column to an array.

```php
class LanguageLine extends Model
{
    public array $translatable = ['text'];
    public array $guarded = ['id'];
    protected array $casts = ['text' => 'array'];
}
```
Tokens:
Raw