signifly/laravel-translator

Database based translations for your Eloquent models.

v2.0.0 2023-11-21 14:19 UTC

README

Latest Version on Packagist Build Status StyleCI Quality Score Total Downloads

The signifly/laravel-translator package allows you to easily add database based translations to your Eloquent models.

Below is a small example of how to use it:

// Add the trait to your translatable models
use Signifly\Translator\Concerns\Translatable;

class Post extends Model
{
    use Translatable;

    /** @var array */
    protected $translatable = [
        'title', 'description',
    ];
}

In order to store translations, you can do the following:

$post = Post::find(1);
$post->translate('en', [
    'title' => 'Some title',
    'description' => 'description',
]);
// returns a Illuminate\Support\Collection of translations

You can also translate a single attribute:

$post->translateAttribute('en', 'title', 'Some title');
// returns Signifly\Translator\Contracts\Translation

If you want to update the model's attributes as well, it can be accomplished using:

Post::createAndTranslate('en', [
    'title' => 'Some title',
    'description' => 'description',
]);

// or when updating
$post->updateAndTranslate('en', [
    'title' => 'New title',
    'description' => 'New description',
]);

The updateAndTranslate method will detect if it is the default language and update accordingly.

Documentation

To get started follow the installation instructions below.

Installation

You can install the package via composer:

composer require signifly/laravel-translator

The package will automatically register itself.

You can publish the migration with:

php artisan vendor:publish --tag="translator-migrations"

Note: The default migration assumes you are using integers for your model IDs. If you are using UUIDs, or some other format, adjust the migration accordingly.

php artisan migrate

You can optionally publish the config file with:

php artisan vendor:publish --tag="translator-config"

This is the contents of the published config file:

return [

    /*
     * The active language code that is used by the package
     * to return the correct language for a model.
     */
    'active_language_code' => null,

    /*
     * By default the package will not translate model attributes automatically.
     * It should be used with caution as it performs extra requests.
     * Remember to eager load the translations
     * in order to optimize performance.
     */
    'auto_translate_attributes' => false,

    /*
     * The default language code that is used by the package
     * to make comparisons against other languages
     * in order to provide statistics.
     */
    'default_language_code' => 'en',

    /*
     * By default the package will use the `lang` paramater
     * to set the active language code.
     */
    'language_parameter' => 'lang',

    /*
     * This determines if the translations can be soft deleted.
     */
    'soft_deletes' => false,

    /*
     * This is the name of the table that will be created by the migration and
     * used by the Translation model shipped with this package.
     */
    'table_name' => 'translations',

    /*
     * This model will be used to store translations.
     * It should be implements the Signifly\Translator\Contracts\Translation interface
     * and extend Illuminate\Database\Eloquent\Model.
     */
    'translation_model' => \Signifly\Translator\Models\Translation::class,

];

Advanced

The package comes with a couple of middlewares that you might want to apply in order to get some extra functionality.

Auto Translation

You can enable this either by setting the auto_translate_attributes to true in the config or applying the Signifly\Translator\Http\Middleware\AutoTranslate middleware to your routes.

For this to work you would also have to set the active_language_code in the config.

Activate Language

This can inferred from the request if you apply the Signifly\Translator\Http\Middleware\ActivateLanguage middleware to your routes.

However, you may also accomplish this manually by calling Translator::activateLanguage('en').

Testing

composer test

Security

If you discover any security issues, please email dev@signifly.com instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.