mguinea/laravel-translatable

Laravel package to make Eloquent models attributes translatables

dev-master 2020-07-24 20:29 UTC

This package is auto-updated.

Last update: 2020-07-24 20:30:02 UTC


README

Make Eloquent model attributes translatables using Translations table

Scrutinizer Code Quality Code Coverage Build Status StyleCI License MIT Laravel Laravel

This package contains a trait to make Eloquent attributes translatable. Translations are stored in Translations database table.

Once the trait is installed on the model you can do these things:

$customer = new Customer; // An Eloquent model
$customer
   ->setTranslation('greeting', 'en', 'Hello')
   ->setTranslation('greeting', 'es', 'Hola')
   ->save();
   
$customer->greeting; // Returns 'Hello' given that the current app locale is 'en'
$customer->getTranslation('greeting', 'es'); // returns 'Hola'

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

$customer->greeting; // Returns 'Hola'

Installation

You can install the package via composer:

composer require mguinea/laravel-translatable

If you want to change the default model or the default tables names, you could publish the config file:

php artisan vendor:publish --provider="Mguinea\Translatable\TranslatableServiceProvider" --tag=config

You must publish the migration file to create polymorphic and main translations tables:

php artisan vendor:publish --provider="Mguinea\Translatable\TranslatableServiceProvider" --tag=migrations

Making a model translatable

The required steps to make a model translatable are:

  • First, you need to add the Mguinea\Translatable\Traits\Translatable trait.
  • Next, you should create a public static property $translatable which holds an array with all the names of attributes you wish to make translatable.

Here's an example of a prepared model:

use Illuminate\Database\Eloquent\Model;
use Mguinea\Translatable\Traits\Translatable;

class Customer extends Model
{
    use Translatable;
       
    protected $fillable = ['greeting'];
    public static $translatable = ['greeting'];
}

Fillable

Guarded

/** * The attributes that are mass assignable. * * @var array */ protected $fillable = [];

/**
 * The attributes that aren't mass assignable.
 *
 * @var array
 */
protected $guarded = ['*'];

/**
 * Indicates if all mass assignment is enabled.
 *
 * @var bool
 */
protected static $unguarded = false;

Available methods

Getting a translation

The easiest way to get a translation for the current locale is to just get the property for the translated attribute. For example (given that greeting is a translatable attribute):

$customer->greeting;

You can also use this method:

public function getTranslation(string $attributeName, string $locale, bool $useFallbackLocale = true): string

This function has an alias named translate.

Getting all translations

You can get all translations by calling getTranslations() without an argument:

$customer->getTranslations();

Setting a translation

The easiest way to set a translation for the current locale is to just set the property for a translatable attribute. For example (given that greetings is a translatable attribute):

$customer->greetings = 'Aloha';

To set a translation for a specific locale you can use this method:

public function setTranslation(string $attributeName, string $locale, string $value)

To actually save the translation, don't forget to save your model.

$customer->setTranslation('greetings', 'ca', 'Hola');

$customer->save();

You are able to store arrays as a translation because internally it is a json field.

$customer->setTranslation('greetings', 'es', ['Hola', 'Saludos']);

$customer->save();

Validation

  • unique attributes TODO

Forgetting a translation

You can forget a translation for a specific field:

public function forgetTranslation(string $attributeName, string $locale)

You can forget all translations for a specific locale:

public function forgetAllTranslations(string $locale)

Getting all translations in one go

public function getTranslations(string $attributeName): array

Setting translations in one go

public function setTranslations(string $attributeName, array $translations)

Here's an example:

$translations = [
   'en' => 'Hello',
   'es' => 'Hola'
];

$customer->setTranslations('name', $translations);

Events

TranslationHasBeenSet

Right after calling setTranslation the Mguinea\Translatable\Events\TranslationHasBeenSet event will be fired.

It has these properties:

/** @var \Illuminate\Database\Eloquent\Model */
public $model;

/** @var string  */
public $attributeName;

/** @var string  */
public $locale;

public $oldValue;
public $newValue;

Creating models

You can immediately set translations when creating a model. Here's an example:

NewsItem::create([
   'name' => [
      'en' => 'Name in English',
      'nl' => 'Naam in het Nederlands'
   ],
]);

Querying translatable attributes

If you're using MySQL 5.7 or above, it's recommended that you use the json data type for housing translations in the db. This will allow you to query these columns like this:

NewsItem::where('name->en', 'Name in English')->get();

Running the tests

After downloading the package and installing dependencies through composer composer install just run phpunit tests

vendor/bin/phpunit

Changelog

Please see CHANGELOG for more information what has changed recently.

Built With

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

Security

If you discover any security related issues, please email develop.marcguinea@gmail.com instead of using the issue tracker.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the MIT License - see the LICENSE file for details

Authors

Acknowledgments