Laravel Translatable

https://github.com/spatie/laravel-translatable
Admin
Laravel Translatable is a trait that makes Eloquent models translatable by storing translations as...
Tokens:7,868
Snippets:99
Trust Score:8.5
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Get translations with return example

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Gets translations for a specific attribute and shows the returned array.

```php
$newsItem->getTranslations('name'); 
// returns ['en' => 'Name in English', 'nl' => 'Naam in het Nederlands']
```

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

### Install package via Composer

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/installation-setup.md

Run this command to install the spatie/laravel-translatable package.

```bash
composer require spatie/laravel-translatable
```

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

### Set and get translations with setTranslation and getTranslation

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

Shows how to set and get translations after applying the trait. Includes setting translations, retrieving by locale, changing the app locale, getting all translations, and translating nested JSON keys using the -> notation.

```php
$newsItem = new NewsItem;
$newsItem
   ->setTranslation('name', 'en', 'Name in English')
   ->setTranslation('name', 'nl', 'Naam in het Nederlands')
   ->save();

$newsItem->name; // Returns 'Name in English' given that the current app locale is 'en'
$newsItem->getTranslation('name', 'nl'); // returns 'Naam in het Nederlands'

app()->setLocale('nl');
$newsItem->name; // Returns 'Naam in het Nederlands'

$newsItem->getTranslations('name'); // returns an array of all name translations

// You can translate nested keys of a JSON column using the -> notation
// First, add the path to the $translatable array, e.g., 'meta->description'
$newsItem
   ->setTranslation('meta->description', 'en', 'Description in English')
   ->setTranslation('meta->description', 'nl', 'Beschrijving in het Nederlands')
   ->save();

$attributeKey = 'meta->description';
$newsItem->$attributeKey; // Returns 'Description in English'
$newsItem->getTranslation('meta->description', 'nl'); // Returns 'Beschrijving in het Nederlands'
```

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

### Run tests with composer test

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

Runs the package's test suite. Use this command in the project root after installing dependencies.

```bash
composer test
```

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

### forgetAllTranslations usage example

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/removing-translations.md

Example of calling forgetAllTranslations to remove all translations for the 'nl' locale.

```php
$newsItem->forgetAllTranslations('nl');
```

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

### Get all translations via accessor

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Uses the translations accessor to get all translations.

```php
$yourModel->translations
```

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

### Customize fallback with missingKeyCallback (return string)

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Uses the missingKeyCallback to return a string that will be used as the fallback translation. The example calls a remote translation service.

```php
use Spatie\Translatable\Facades\Translatable;
use App\Service\MyRemoteTranslationService;

Translatable::fallback(missingKeyCallback: function (
    Model $model, 
    string $translationKey, 
    string $locale, 
    string $fallbackTranslation, 
    string $fallbackLocale
    ) {
    
    return MyRemoteTranslationService::getAutomaticTranslation($fallbackTranslation, $fallbackLocale, $locale);
});
```

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

### Translations helper usage examples

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/advanced-usage/usage-with-factories.md

Shows several ways to call the translations helper, including with a single locale, multiple locales with the same value, and multiple locales with different values. The output is shown in comments.

```php
/** @var $this \Illuminate\Database\Eloquent\Factories\Factory */

$this->translations('en', 'english')
// output: ['en' => 'english']

$this->translations(['en', 'nl'], 'english')
// output: ['en' => 'english', 'nl' => 'english']

$this->translations(['en', 'nl'], ['english', 'dutch'])
// output: ['en' => 'english', 'nl' => 'dutch']
```

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

### Get translation by accessing property

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Gets the translation for the current locale by accessing the translatable attribute.

```php
$newsItem->name;
```

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

### Get all translations with getTranslations()

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Calls getTranslations() without an argument to retrieve all translations.

```php
$newsItem->getTranslations();
```

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

### Factory definition using translations helper

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/advanced-usage/usage-with-factories.md

Example of a UserFactory definition that uses the translations helper to set a translated 'bio' attribute.

```php
class UserFactory extends \Illuminate\Database\Eloquent\Factories\Factory {
    public function definition(): array
    {
        return [
            'bio' => $this->translations('en', 'english'),
        ];
    }
}
```

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

### Customize fallback with missingKeyCallback (logging)

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Registers a closure as the $missingKeyCallback to run custom code when a translation key is missing. The example logs a warning with details about the missing key.

```php
use Spatie\Translatable\Facades\Translatable;
use Illuminate\Support\Facades\Log;

Translatable::fallback(missingKeyCallback: function (
   Model $model, 
   string $translationKey, 
   string $locale, 
   string $fallbackTranslation, 
   string $fallbackLocale,
) {

    // do something (ex: logging, alerting, etc)
    
    Log::warning('Some translation key is missing from an eloquent model', [
       'key' => $translationKey,
       'locale' => $locale,
       'fallback_locale' => $fallbackLocale,
       'fallback_translation' => $fallbackTranslation,
       'model_id' => $model->id,
       'model_class' => get_class($model), 
    ]);
});
```

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

### replaceTranslations method signature and usage example

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/replacing-translations.md

The method signature for replaceTranslations, which replaces all translations for a single key. The example shows setting translations, then replacing them with a subset, and confirms the result via getTranslations().

```php
public function replaceTranslations(string $key, array $translations)
```

```php
$translations = ['en' => 'hello', 'es' => 'hola'];

$newsItem->setTranslations('hello', $translations);
$newsItem->getTranslations(); // ['en' => 'hello', 'es' => 'hola']

$newTranslations = ['en' => 'hello'];

$newsItem->replaceTranslations('hello', $newTranslations);
$newsItem->getTranslations(); // ['en' => 'hello']
```

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

### forgetTranslation usage example

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/removing-translations.md

Example of calling forgetTranslation to remove the 'nl' translation for the 'name' attribute.

```php
$newsItem->forgetTranslation('name', 'nl');
```

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

### Get locales that a model has

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Sets translations, saves the model, and calls locales() to get all locales the model has.

```php
   $translations = ['en' => 'hello', 'es' => 'hola'];
   $newsItem->name = $translations;
   $newsItem->save();

   $newsItem->locales(); // returns ['en', 'es']
```

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

### getTranslations method signature with allowed locales

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Method signature for getting translations for specific locales.

```php
public function getTranslations(string $attributeName, array $allowedLocales): array
```

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

### Get translations for specific locales

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Sets translations for multiple locales and retrieves only the specified ones.

```php
$translations = [
    'en' => 'Hello',
    'fr' => 'Bonjour',
    'de' => 'Hallo',
];

$newsItem->setTranslations('hello', $translations);
$newsItem->getTranslations('hello', ['en', 'fr']); // returns ['en' => 'Hello', 'fr' => 'Bonjour']
```

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

### getTranslation method signature

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Method signature for getting a translation for a specific locale with an optional fallback.

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

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

### Set and get translations on an Eloquent model

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/introduction.md

Use the setTranslation method to store translations for a model attribute in multiple locales, then retrieve them with getTranslation or the attribute accessor. The attribute accessor returns the translation for the current app locale, which can be changed with app()->setLocale().

```php
$newsItem = new NewsItem(); // This is an Eloquent model
$newsItem
   ->setTranslation('name', 'en', 'Name in English')
   ->setTranslation('name', 'nl', 'Naam in het Nederlands')
   ->save();

$newsItem->name; // Returns 'Name in English' given that the current app locale is 'en'
$newsItem->getTranslation('name', 'nl'); // returns 'Naam in het Nederlands'

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

$newsItem->name; // Returns 'Naam in het Nederlands'
```

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

### Set up fallback with Translatable::fallback

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Sets up fallback behavior for missing translations. Typically placed in a service provider. The fallback method accepts named parameters for configuration.

```php
    // typically, in a service provider
        
    use Spatie\Translatable\Facades\Translatable;
    
    Translatable::fallback(
        ...
    );
```

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

### Translations helper outside factories

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/advanced-usage/usage-with-factories.md

Shows how to use the translations helper statically outside of a factory instance, with the same output as the instance method.

```php
\Illuminate\Database\Eloquent\Factories\Factory::translations('en', 'english');
// output: ['en' => 'english']
```

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

### Create model with translations

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Creates a new model instance with translations for multiple locales at once.

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

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

### Set translation by assigning property

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Sets the translation for the current locale by assigning a value to the translatable attribute.

```php
$newsItem->name = 'New translation';
```

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

### Fallback to any locale with fallbackAny

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Falls back to any available translation when neither the preferred locale nor the fallback locale has a translation. Pass $fallbackAny as true.

```php
    use Spatie\Translatable\Facades\Translatable;

    Translatable::fallback(
         fallbackAny: true,
    );
```

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

### Query translatable models with locale scopes

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

Provides scoped queries for retrieving records based on locales. Includes whereLocale, whereLocales, whereJsonContainsLocale, and whereJsonContainsLocales, with an optional operand argument for LIKE queries.

```php
// Returns all news items with a name in English
NewsItem::whereLocale('name', 'en')->get();

// Returns all news items with a name in English or Dutch
NewsItem::whereLocales('name', ['en', 'nl'])->get();

// Returns all news items that has name in English with value `Name in English` 
NewsItem::query()->whereJsonContainsLocale('name', 'en', 'Name in English')->get();

// Returns all news items that has name in English or Dutch with value `Name in English` 
NewsItem::query()->whereJsonContainsLocales('name', ['en', 'nl'], 'Name in English')->get();

// The last argument is the "operand" which you can tweak to achieve something like this:

// Returns all news items that has name in English with value like `Name in...` 
NewsItem::query()->whereJsonContainsLocale('name', 'en', 'Name in%', 'like')->get();

// Returns all news items that has name in English or Dutch with value like `Name in...` 
NewsItem::query()->whereJsonContainsLocales('name', ['en', 'nl'], 'Name in%', 'like')->get();
```

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

### Query translations by locale with whereLocale and whereLocales

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/querying-translations.md

Query records based on locales using the whereLocale and whereLocales methods. whereLocale checks a single locale, while whereLocales checks multiple locales.

```php
NewsItem::whereLocale('name', 'en')->get(); // Returns all news items with a name in English

NewsItem::whereLocales('name', ['en', 'nl'])->get(); // Returns all news items with a name in English or Dutch
```

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

### Fallback to a specific locale with fallbackLocale

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Falls back to a specific locale ('fr') instead of the app's fallback locale from config/app.php. Pass the locale as the $fallbackLocale parameter.

```php
    use Spatie\Translatable\Facades\Translatable;

    Translatable::fallback(
        fallbackLocale: 'fr',
    );
```

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

### Make a model translatable with #[Translatable] attribute

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/installation-setup.md

Add the HasTranslations trait and use the #[Translatable] attribute to declare translatable columns. The attribute accepts a variadic list of column names.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\Attributes\Translatable;
use Spatie\Translatable\HasTranslations;

#[Translatable('name', 'description')]
class NewsItem extends Model
{
    use HasTranslations;
}
```

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

### Set translation and save model

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Sets the translation for the current locale and saves the model to persist the change.

```php
$newsItem->name = 'New translation'
$newsItem->save();
```

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

### Set translations for multiple languages

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Sets translations for multiple locales by assigning an array or using the setTranslations method, then saves the model.

```php
$translations = ['en' => 'hello', 'es' => 'hola'];
$newsItem->name = $translations;

// alternatively, use the `setTranslations` method

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

$newsItem->save();
```

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

### Per-model fallback locale with getFallbackLocale()

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Defines a per-model fallback locale by implementing getFallbackLocale() on the model. The method returns the value of the 'fallback_locale' attribute.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;

class NewsItem extends Model
{
    use HasTranslations;

    public $fillable = ['name', 'fallback_locale'];

    public $translatable = ['name'];

    public function getFallbackLocale() : string
    {
        return $this->fallback_locale;
    }
}
```

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

### Make a model translatable with $translatable property

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/installation-setup.md

Alternatively, declare translatable attributes via a public $translatable property. When both the property and the attribute are present, their values are merged and deduplicated.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;

class NewsItem extends Model
{
    use HasTranslations;

    public array $translatable = ['name'];
}
```

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

### setTranslation method signature

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/getting-and-settings-translations.md

Method signature for setting a translation for a specific locale.

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

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

### Query translations by locale value with whereJsonContainsLocale and whereJsonContainsLocales

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/querying-translations.md

Query records based on locale's value using whereJsonContainsLocale and whereJsonContainsLocales methods. These methods check for a specific value within the JSON translation column for one or multiple locales.

```php
// Returns all news items that has name in English with value `Name in English` 
NewsItem::query()->whereJsonContainsLocale('name', 'en', 'Name in English')->get(); 

// Returns all news items that has name in English or Dutch with value `Name in English` 
NewsItem::query()->whereJsonContainsLocales('name', ['en', 'nl'], 'Name in English')->get(); 
```

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

### TranslationHasBeenSetEvent class definition

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/advanced-usage/available-events.md

The event class is fired after calling setTranslation. It contains public properties for the model, key, locale, oldValue, and newValue.

```php
namespace Spatie\Translatable\Events;

class TranslationHasBeenSetEvent
{
    public function __construct(
        public mixed $model,
        public string $key,
        public string $locale,
        public mixed $oldValue,
        public mixed $newValue,
    ) {
        //
    }
}
```

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

### Customize toArray() for translatable attributes

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/advanced-usage/customize-the-toarray-method.md

Override the toArray() method in a custom trait that wraps Spatie\Translatable\HasTranslations. It serializes translatable attributes using the current locale via App::getLocale(), while preserving only attributes selected by the query and merging relations.

```php
namespace App\Traits;
use Spatie\Translatable\HasTranslations as BaseHasTranslations;

trait HasTranslations
{
    use BaseHasTranslations;

    public function toArray()
    {
        $attributes = $this->attributesToArray(); // attributes selected by the query
        // remove attributes if they are not selected
        $translatables = array_filter($this->getTranslatableAttributes(), function ($key) use ($attributes) {
            return array_key_exists($key, $attributes);
        });
        foreach ($translatables as $field) {
            $attributes[$field] = $this->getTranslation($field, \App::getLocale());
        }
        return array_merge($attributes, $this->relationsToArray());
    }
}
```

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

### Query JSON translation column with whereRaw and JSON_EXTRACT

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/querying-translations.md

Query translations using JSON_EXTRACT for MariaDB 10.2.3 or above. This is an alternative to the arrow syntax for MySQL.

```php
NewsItem::whereRaw("JSON_EXTRACT(name, '$.en') = 'Name in English'")->get();
```

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

### Query JSON translation column with where

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/querying-translations.md

Query translations using the JSON data type in MySQL 5.7 or above. The arrow syntax accesses the 'en' locale key within the JSON column.

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

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

### forgetAllTranslations method signature

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/removing-translations.md

Signature of the forgetAllTranslations method. Use it to remove all translations for a specific locale.

```php
public function forgetAllTranslations(string $locale)
```

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

### Disable fallback per model with $useFallbackLocale

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/handling-missing-translations.md

Disables fallback behavior for a specific model by setting the protected $useFallbackLocale property to false. By default, fallback is used when accessing a non-existent translation attribute.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;

class NewsItem extends Model
{
    use HasTranslations;

    public $translatable = ['name'];
    
    protected $useFallbackLocale = false;
}
```

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

### forgetTranslation method signature

Source: https://github.com/spatie/laravel-translatable/blob/main/docs/basic-usage/removing-translations.md

Signature of the forgetTranslation method. Use it to remove a translation for a specific attribute and locale.

```php
public function forgetTranslation(string $attributeName, string $locale)
```
Tokens:
Raw