If you want to load translations from a source other than the database (e.g., YAML or CSV files), you can implement the Spatie\TranslationLoader\TranslationLoaders\TranslationLoader interface.

Your implementation must include the loadTranslations method, which returns an array of translations for a specific locale and group. Once implemented, register your class in the translation_loaders array within the package configuration file.

namespace Spatie\TranslationLoader\TranslationLoaders;

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

Install the package via Composer and replace the default Laravel translation service provider with the one provided by this package. You must also publish and run the migrations to create the language_lines table.

composer require spatie/laravel-translation-loader

In config/app.php (Laravel) or bootstrap/app.php (Lumen), replace:

Illuminate\Translation\TranslationServiceProvider::class,

with:

Spatie\TranslationLoader\TranslationServiceProvider::class,

Publish and run migrations

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

You can publish the configuration file to customize which loaders are used, which model is used for database translations, and which manager handles the translations.

Note: In Lumen, publishing assets via Artisan commands does not work out of the box; you must manually copy the files from the repository.

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

The package allows you to specify which class should be used as the translation.loader via the translation-loader.translation_manager configuration key. This class is instantiated as a singleton and is responsible for loading translation lines. By default, the package uses a manager that replaces the standard Laravel FileLoader.

// In your config/translation-loader.php
return [
    'translation_manager' => Spatie\TranslationLoader\TranslationLoaderManager::class,
];

The Db translation loader relies on a specific Eloquent model to fetch translations from the database. You must configure this model in your config/translation-loader.php file using the model key.

The configured model class must implement or extend the Spatie\TranslationLoader\LanguageLine class to ensure it has the necessary getTranslationsForGroup method.

// config/translation-loader.php

return [
    'model' => App\Models\LanguageLine::class,
];

The following keys are available in the published configuration file:

• translation_loaders: An array of classes that implement Spatie\TranslationLoader\TranslationLoaders\TranslationLoader. These are the sources used to fetch translations.
• model: The Eloquent model used by the Db translation loader. It must extend Spatie\TranslationLoader\LanguageLine.
• translation_manager: The class responsible for overriding the default Laravel translation.loader.

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

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

    'translation_manager' => Spatie\TranslationLoader\TranslationLoaderManager::class,
];

If you encounter an InvalidConfiguration exception, it typically means the model class you have configured for the translation loader is incorrect. Specifically, the class you provided must extend Spatie\TranslationLoader\LanguageLine.

If you see the error message You have configured an invalid class {className}. A valid class extends Spatie\TranslationLoader\LanguageLine., ensure that your custom model implementation correctly inherits from the required base class.

If you need to manually clear the cached translations for a specific group, you can call flushGroupCache() on a LanguageLine instance. This will remove the cached entries for all locales present in that specific line's text attribute.

Note: The model automatically handles cache flushing on saved and deleted events, so manual flushing is typically only necessary for custom cache management logic.

$languageLine->flushGroupCache();