Laravel Translatable

https://github.com/astrotomic/laravel-translatable
Admin
Laravel Translatable is a Laravel package for translatable models that simplifies retrieving and...
Tokens:30,775
Snippets:268
Trust Score:9.7
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install Laravel Translatable via Composer

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

Use this command to install the package via Composer.

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

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

### all() method output example

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Shows the structure of the array returned by all() or toArray(). The returned array combines country locales with language locales, as shown.

```php
[
  'en',
  'de',
  'es',
  'es-MX',
  'es-CO',
]
```

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

### Configure rule_factory in config/translatable.php

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/validation-rule-factory.md

Adjust the default format, prefix, and suffix used by the factory in the package configuration file. The example sets the format to FORMAT_ARRAY and uses '%' as both prefix and suffix.

```php
'rule_factory' => [
    'format' => \Astrotomic\Translatable\Validation\RuleFactory::FORMAT_ARRAY,
    'prefix' => '%',
    'suffix' => '%',
]
```

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

### get(string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Returns the provided locale or null if it's not set.

```APIDOC
## get(string $locale)

### Description
Returns the provided locale or `null` if it's not set. This isn't really useful except you want to build your own check if a locale is set.

### Method
get

### Parameters
- **$locale** (string) - Required - The locale to get

### Return Value
- **string|null** - The locale if set, otherwise null
```

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

### listsTranslations scope with example output

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns an array of post ids and the translated title attribute for the given translation field. The output example shows the resulting array structure.

```php
Post::listsTranslations('title')->get()->toArray();
```

```php
[
    ['id' => 1, 'title' => 'My first post'],
    ['id' => 2, 'title' => 'My second post']
]
```

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

### Override format, prefix, suffix, and locales at runtime

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/validation-rule-factory.md

Pass parameters to RuleFactory::make() to change the format, prefix, suffix, and locales at runtime. This example uses FORMAT_KEY, '{' and '}' as delimiters, and only 'en' and 'de' as locales. Only defined locales are allowed; using an undefined locale throws an InvalidArgumentException.

```php
RuleFactory::make($rules, RuleFactory::FORMAT_KEY, '{', '}', [
    'en',
    'de',
]);
```

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

### Enable property fallback in config

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Add `'use_property_fallback' => true` to the config to enable fallback for empty properties. This is enabled by default on new installations but must be added manually if the config was created before v7.1.

```php
'use_property_fallback' => true,
```

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

### translateOrNew

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Gets a translation instance using the default or given locale, returning a new translation model when the locale is not present.

```php
$post->translateOrNew(); // returns the german translation model
$post->translateOrNew('fr'); // returns the french translation model
$post->translateOrNew('it'); // returns the new italian translation model
```

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

### translate

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Gets a translation instance using the default or given locale inferring fallback to the configured fallback_locale when the locale is missing, unless $withFallback is true.

```php
$post->translate(); // returns the german translation model
$post->translate('fr'); // returns the french translation model
$post->translate('it'); // returns null
$post->translate('it', true); // returns the english translation model
```

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

### Create locale-aware validation rules with RuleFactory::make

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/validation-rule-factory.md

Use RuleFactory::make() to define validation rules with placeholders like %title% and %content%. The factory expands these placeholders to all configured locales, producing an array of rules with locale-specific keys. The example shows the resulting array for locales en, de, de-DE, and de-AT.

```php
$rules = RuleFactory::make([
    'translations.%title%' => 'sometimes|string',
    'translations.%content%' => ['required_with:translations.%title%', 'string'],
]);

$validatedData = $request->validate($rules);
```

```php
[
    'translations.en.title' => 'sometimes|string',
    'translations.de.title' => 'sometimes|string',
    'translations.de-DE.title' => 'sometimes|string',
    'translations.de-AT.title' => 'sometimes|string',

    'translations.en.content' => ['required_with:translations.en.title', 'string'],
    'translations.de.content' => ['required_with:translations.de.title', 'string'],
    'translations.de-DE.content' => ['required_with:translations.de-DE.title', 'string'],
    'translations.de-AT.content' => ['required_with:translations.de-AT.title', 'string'],
]
```

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

### Select a model by translated field with whereHas

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/faq.md

Use this query to find a model by its translated field value. In this example, it retrieves the first Post whose translation locale is 'en' and whose title equals 'My first post'.

```php
Post::whereHas('translations', function ($query) {
    $query
        ->where('locale', 'en')
        ->where('title', 'My first post');
})->first();
```

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

### translateOrDefault

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Gets a translation instance using the default or given locale, always using the fallback locale when the requested one is absent.

```php
$post->translateOrDefault(); // returns the german translation model
$post->translateOrDefault('fr'); // returns the french translation model
$post->translateOrDefault('it'); // returns the english translation model
```

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

### Getting translated attributes

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

Retrieve a translated attribute for a specific locale using the translate method, or by setting the application locale.

```php
$post = Post::first();
echo $post->translate('en')->title; // My first post

App::setLocale('en');
echo $post->title; // My first post

App::setLocale('de');
echo $post->title; // Mein erster Post
```

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

### Publish translatable configuration

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

Publish the package configuration file to your project. After running this, you must configure the 'locales' key.

```bash
php artisan vendor:publish --tag=translatable
```

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

### load()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Reloads all locales from the translatable.locales config.

```APIDOC
## load()

### Description
This method will (re)load all locales from the `translatable.locales` config. It is called during service instantiation, so you will only need it if you change the config during runtime.

### Method
load

### Parameters
None

### Return Value
None
```

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

### replicateWithTranslations

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Creates a clone of the post along with its translations.

```php
$replicate = $post->replicateWithTranslations();
```

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

### all()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Returns all available locales as an array.

```APIDOC
## all()

### Description
Returns all available locales as an array. The structure differs from the config one; it returns the final generated array with combined country locales.

### Method
all

### Parameters
None

### Return Value
- **array** - List of all available locales, e.g., ['en', 'de', 'es', 'es-MX', 'es-CO']
```

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

### Set InnoDB engine for new tables in migration

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/faq.md

For new tables, set the storage engine to 'InnoDB' in the migration to avoid foreign key constraint errors. This is a quick solution, but the best fix is to update your MySQL version.

```php
Schema::create('language_translations', function(Blueprint $table){
  $table->engine = 'InnoDB';
  $table->increments('id');
    // ...
});
```

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

### Enable fallback with null locale to use first defined

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Set `fallback_locale` to null to automatically use the first defined locale in the `locales` array. The order is: simple language locales first, then country-based ones.

```php
[
    // ...
    'use_fallback' => true,
    'fallback_locale' => null,
    'locales' => [
        'en',
        'de' => [
            'DE',
            'AT',
            'CH',
        ],
    ]
    // ...
]
```

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

### Configure locales array in config/translatable.php

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

Configure the locales your app should use. There is no restriction on the format; you can use 'eng' instead of 'en'. This is the only configuration key you have to adjust.

```php
'locales' => [
    'en',
    'fr',
    'es' => [
        'MX', // mexican spanish
        'CO', // colombian spanish
    ],
],
```

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

### Fill multiple translations with wrapper in Laravel

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

Shows how to create a model with translations wrapped under the 'translations' key as configured.

```php
$data = [
  'author' => 'Gummibeer',
  'translations' => [
      'en' => ['title' => 'My first post'],
      'fr' => ['title' => 'Mon premier post'],
  ],
];
$post = Post::create($data);

echo $post->translate('fr')->title; // Mon premier post
```

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

### current()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Returns the current locale string.

```APIDOC
## current()

### Description
Returns the current locale string.

### Method
current

### Parameters
None

### Return Value
- **string** - The current locale
```

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

### Form input array syntax for locales

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/forms.md

Use input name arrays to structure form inputs for multiple locales without manipulating form data. This syntax uses locale as the first key.

```markup
<input type="text" name="en[title]" />
<input type="text" name="de[title]" />
```

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

### replicateWithTranslations(array $except = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Creates a clone of the model and clones its translations.

```APIDOC
## replicateWithTranslations(array $except = null)

### Description
Creates a clone of the model and clones its translations.

### Method
`replicateWithTranslations`

### Parameters
- **$except** (array) - Optional - An array of attributes to exclude from the replication.

### Returns
- **Post** - The replicated model instance.

### Example
```php
$replicate = $post->replicateWithTranslations();
```
```

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

### Define Post model with Translatable trait

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

Define the translatable model. Use the Astrotomic\Translatable\Translatable trait and implement the TranslatableContract. Set $translatedAttributes to the fields translated in the translation model.

```php
use Astrotomic\Translatable\Contracts\Translatable as TranslatableContract;
use Astrotomic\Translatable\Translatable;

class Post extends Model implements TranslatableContract
{
    use Translatable;

    public $translatedAttributes = ['title', 'content'];
    protected $fillable = ['author'];
}
```

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

### translate(?string $locale = null, bool $withFallback = false)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns an instance of the translation model using the default or given locale, optionally using the fallback locale if the requested locale is not present.

```APIDOC
## translate(?string $locale = null, bool $withFallback = false)

### Description
Returns an instance of the translation model using the default or given locale. If the locale is not found and `$withFallback` is true, it returns the fallback locale translation.

### Method
`translate`

### Parameters
- **$locale** (?string) - Optional - The locale to retrieve the translation for. Defaults to the current locale.
- **$withFallback** (bool) - Optional - Whether to use the fallback locale if the requested locale is not found. Defaults to false.

### Returns
- **PostTranslation|null** - The translation model instance or null if not found and no fallback.

### Example
```php
$post->translate(); // returns the german translation model
$post->translate('fr'); // returns the french translation model
$post->translate('it'); // returns null
$post->translate('it', true); // returns the english translation model
```
```

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

### Migrate existing table to use laravel-translatable

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/faq.md

Use these migration commands to migrate existing English data into the new translation table and then remove the original columns from the main table. Run the insert statement first to copy the existing attributes, then drop the columns.

```php
\DB::statement("insert into country_translations (country_id, name, locale) select id, name, 'en' from countries");

// We drop the translation attributes in our main table:
Schema::table('posts', function ($table) {
    $table->dropColumn('title');
    $table->dropColumn('content');
});
```

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

### Filling multiple translations

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

Create a model with translations for multiple locales by passing an array with locale keys.

```php
$data = [
  'author' => 'Gummibeer',
  'en' => ['title' => 'My first post'],
  'fr' => ['title' => 'Mon premier post'],
];
$post = Post::create($data);

echo $post->translate('fr')->title; // Mon premier post
```

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

### setDefaultLocale

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Sets the default locale for the current model and demonstrates retrieving it.

```php
$post->setDefaultLocale('fr');
$post->getDefaultLocale(); // 'fr'
```

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

### add(string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Adds a locale to the set of available locales.

```APIDOC
## add(string $locale)

### Description
Adds the given locale to the set of available locales. The set of available locales will keep unique and this method won't throw an exception if the locale is already present.

### Method
add

### Parameters
- **$locale** (string) - Required - The locale to add

### Return Value
None
```

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

### Enable fallback with a default locale

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Set `use_fallback` to true and `fallback_locale` to a specific locale (e.g., 'en') to use that translation when a translation is missing.

```php
[
    // ...
    'use_fallback' => true,
    'fallback_locale' => 'en',
    // ...
]
```

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

### Migrations for posts and post_translations tables

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

Two migrations for a Post model and its translations. The posts table stores non-translatable fields, while the post_translations table stores locale-specific fields and links to the parent post.

```php
Schema::create('posts', function(Blueprint $table) {
    $table->increments('id');
    $table->string('author');
    $table->timestamps();
});
```

```php
Schema::create('post_translations', function(Blueprint $table) {
    $table->increments('id');
    $table->integer('post_id')->unsigned();
    $table->string('locale')->index();
    $table->string('title');
    $table->text('content');

    $table->unique(['post_id', 'locale']);
    $table->foreign('post_id')->references('id')->on('posts')->onDelete('cascade');
});
```

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

### Form input colon notation for locales

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/forms.md

Alternative colon notation for request inputs. Note that with this approach the attribute goes first, followed by the locale.

```markup
<input type="text" name="title:en" />
<input type="text" name="title:de" />
```

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

### Filling multiple translations wrapped

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

Use a wrapper property to group translations when creating a model. First set the translations_wrapper property in the config file, then pass translations under that key.

```php
'translations_wrapper' => 'translations',
```

```php
$data = [
  'author' => 'Gummibeer',
  'translations' => [
      'en' => ['title' => 'My first post'],
      'fr' => ['title' => 'Mon premier post'],
  ],
];
$post = Post::create($data);

echo $post->translate('fr')->title; // Mon premier post
```

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

### translateOrNew(?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns an instance of the translation model using the default or given locale, creating a new instance if the translation does not exist.

```APIDOC
## translateOrNew(?string $locale = null)

### Description
Returns an instance of the translation model using the default or given locale. If the translation does not exist, a new instance is created.

### Method
`translateOrNew`

### Parameters
- **$locale** (?string) - Optional - The locale to retrieve the translation for. Defaults to the current locale.

### Returns
- **PostTranslation** - The translation model instance, either existing or new.

### Example
```php
$post->translateOrNew(); // returns the german translation model
$post->translateOrNew('fr'); // returns the french translation model
$post->translateOrNew('it'); // returns the new italian translation model
```
```

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

### Configure translations_wrapper in translatable config

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

Set the translations_wrapper property in the translatable config file to use a custom wrapper key.

```php
'translations_wrapper' => 'translations',
```

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

### Configure country-based locales

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Define locales with country codes as sub-arrays. The fallback for a locale like `es-MX` will first try `es`, then the configured fallback locale.

```php
    'locales' => [
        'en',
        'es' => [
            'MX',
            'CO',
        ],
    ];
```

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

### has(string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Checks if a given locale is available in the configured set of locales.

```APIDOC
## has(string $locale)

### Description
Checks if the given locale is available in the configured set of locales.

### Method
has

### Parameters
- **$locale** (string) - Required - The locale to check

### Return Value
- **bool** - True if the locale is available, false otherwise
```

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

### Update model with request data

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/forms.md

Save the request data directly to the model. Both array and colon syntax are ready to be saved without further modification.

```php
public function update(Request $request, Post $post)
{
  $post->update($request->all());
}
```

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

### Custom foreign key with ChildPost and ChildPostTranslation

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

Custom foreign key scenario for single table inheritance. ChildPost inherits from Post, uses the same table, and requires a custom translation class. Set $translationForeignKey to 'post_id' to match the existing foreign key.

```php
class ChildPost extends Post
{
    protected $table = 'posts';
}
```

```php
use Illuminate\Database\Eloquent\Model;

class ChildPostTranslation extends Model
{
    protected $table = 'post_translations';
    public $timestamps = false;
    protected $fillable = ['title', 'content'];
}
```

```php
class ChildPost extends Post
{
    protected $table = 'posts';
    protected $translationForeignKey = 'post_id';
}
```

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

### setDefaultLocale(?string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Sets the default locale for the current model.

```APIDOC
## setDefaultLocale(?string $locale)

### Description
Sets the default locale for the current model.

### Method
`setDefaultLocale`

### Parameters
- **$locale** (?string) - Required - The locale to set as default.

### Example
```php
$post->setDefaultLocale('fr');
$post->getDefaultLocale(); // 'fr'
```
```

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

### static enableAutoloadTranslations()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Forces the model to load all translations when toArray() is called.

```APIDOC
## static enableAutoloadTranslations()

### Description
Forces the model to load all translations when `toArray()` is called.

### Method
`enableAutoloadTranslations`

### Example
```php
Post::enableAutoloadTranslations();
```
```

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

### Define PostTranslation model

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

Define the translation model. By convention, it is named PostTranslation. It should have $timestamps set to false and $fillable containing the translated fields.

```php
class PostTranslation extends Model
{
    public $timestamps = false;
    protected $fillable = ['title', 'content'];
}
```

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

### static defaultAutoloadTranslations()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Does not change the default behavior logic for autoloading translations.

```APIDOC
## static defaultAutoloadTranslations()

### Description
Does not change the default behavior logic for autoloading translations.

### Method
`defaultAutoloadTranslations`

### Example
```php
Post::defaultAutoloadTranslations();
```
```

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

### getLocaleSeparator()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Returns the configured locale separator.

```APIDOC
## getLocaleSeparator()

### Description
Returns the configured `translatable.locale_separator` locale separator used to combine language with country locales.

### Method
getLocaleSeparator

### Parameters
None

### Return Value
- **string** - The locale separator
```

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

### withTranslation()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Eager loads the translation relationship only for the default and fallback (if enabled) locale.

```APIDOC
## withTranslation()

### Description
Eager loads translation relationship only for the default and fallback (if enabled) locale.

### Method
Query Scope

### Parameters
None

### Example
```php
Post::withTranslation()->get();
```
```

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

### Set custom locale separator

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Use `'locale_separator' => '_'` to change the separator between language and country from the default `-` to `_` (e.g., `es_MX` instead of `es-MX`).

```php
'locale_separator' => '_',
```

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

### translatedIn(?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns all posts that have a translation in the given locale. If no locale is provided, the current locale is used.

```APIDOC
## translatedIn(?string $locale = null)

### Description
Returns all posts being translated in the specified locale.

### Method
Query Scope

### Parameters
- **$locale** (?string) - Optional - The locale to filter by. Defaults to the current locale.

### Example
```php
Post::translatedIn('en')->get();
```
```

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

### Fix MyISAM migration error by changing engine to InnoDB

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/faq.md

For existing tables that use MyISAM, add this migration to change the table engine to InnoDB before adding foreign key constraints. The down method reverts the engine back to MyISAM.

```php
public function up()
{
    DB::statement('ALTER TABLE countries ENGINE=InnoDB');
}

public function down()
{
    DB::statement('ALTER TABLE countries ENGINE=MyISAM');
}
```

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

### Define TranslatableProtected Interface

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/interface.md

The protected interface defines methods that are part of the package's internal API. Changes to these methods trigger a new major release. It includes `isEmptyTranslatableAttribute` to detect empty translation attribute values and `saveTranslations` to save all attached translations.

```php
interface TranslatableProtected
{
    // detect if a given translation attribute value is empty or not
    protected function isEmptyTranslatableAttribute(string $key, $value): bool;

    // save all attached translations
    protected function saveTranslations(): bool;
}
```

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

### whereTranslationLike(string $translationField, $value, ?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Filters posts by checking the translation against a LIKE pattern.

```APIDOC
## whereTranslationLike(string $translationField, $value, ?string $locale = null)

### Description
Filters posts by checking the translation against a LIKE pattern.

### Method
Query Scope

### Parameters
- **$translationField** (string) - Required - The name of the translated attribute to filter on.
- **$value** (string) - Required - The LIKE pattern to match.
- **$locale** (?string) - Optional - The locale to filter by. Defaults to the current locale.

### Example
```php
Post::whereTranslationLike('title', '%first%')->first();
```
```

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

### translateOrDefault(?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns an instance of the translation model using the default or given locale, always using the fallback locale if the requested locale is not present.

```APIDOC
## translateOrDefault(?string $locale = null)

### Description
Returns an instance of the translation model using the default or given locale. If the locale is not found, it returns the fallback locale translation.

### Method
`translateOrDefault`

### Parameters
- **$locale** (?string) - Optional - The locale to retrieve the translation for. Defaults to the current locale.

### Returns
- **PostTranslation** - The translation model instance.

### Example
```php
$post->translateOrDefault(); // returns the german translation model
$post->translateOrDefault('fr'); // returns the french translation model
$post->translateOrDefault('it'); // returns the english translation model
```
```

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

### Update default locale via fill method

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/forms.md

Update the default locale attributes by passing a single array to the fill method.

```php
$post->fill(['title' => 'My first post']); // Will update the English translatable model
```

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

### translated()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns all posts that have at least one translation.

```APIDOC
## translated()

### Description
Returns all posts with existing translations.

### Method
Query Scope

### Parameters
None

### Example
```php
Post::translated()->get();
```
```

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

### Fill translatable attributes in multiple locales

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/forms.md

Use the overridden fill() method to translate a field in multiple locales with a single form. Pass an array with locales as first array keys and translated attributes in sub-arrays.

```php
$post->fill([
  'en' => [
    'title' => 'My first edited post',
  ],
  'de' => [
    'title' => 'Mein erster bearbeiteter Beitrag',
  ],
]);
```

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

### notTranslatedIn(?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns all posts that do not have a translation in the given locale. If no locale is provided, the current locale is used.

```APIDOC
## notTranslatedIn(?string $locale = null)

### Description
Returns all posts not being translated in the specified locale.

### Method
Query Scope

### Parameters
- **$locale** (?string) - Optional - The locale to filter by. Defaults to the current locale.

### Example
```php
Post::notTranslatedIn('en')->get();
```
```

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

### Enable fallback per model

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Set the `$useTranslationFallback` property to true on a model to enable fallback for that model specifically.

```php
class Post extends Model
{
    public $useTranslationFallback = true;
}
```

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

### whereTranslationLike scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Filters posts by checking the translation against a LIKE pattern. Use this for partial matches on the translation field.

```php
Post::whereTranslationLike('title', '%first%')->first();
```

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

### whereTranslation(string $translationField, $value, ?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Filters posts by checking the translation against the given value.

```APIDOC
## whereTranslation(string $translationField, $value, ?string $locale = null)

### Description
Filters posts by checking the translation against the given value.

### Method
Query Scope

### Parameters
- **$translationField** (string) - Required - The name of the translated attribute to filter on.
- **$value** (mixed) - Required - The value to compare against.
- **$locale** (?string) - Optional - The locale to filter by. Defaults to the current locale.

### Example
```php
Post::whereTranslation('title', 'My first post')->first();
```
```

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

### getDefaultLocale()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns the current default locale for the current model or null if no default locale is set.

```APIDOC
## getDefaultLocale()

### Description
Returns the current default locale for the current model or null if no default locale is set.

### Method
`getDefaultLocale`

### Returns
- **string|null** - The default locale or null.

### Example
```php
$post->getDefaultLocale(); // null
```
```

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

### Use Rule::translatableUnique with Illuminate Rule import

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/custom-validation-rule.md

Use the Rule::translatableUnique method with the Illuminate\Validation\Rule import. This is the same as the previous option but with the import of the Rule class from the Illuminate namespace. The method is used for unique validation on a locale-specific attribute.

```php
use Illuminate\Validation\Rule;
...

$person = new Person(['name' => 'john doe']);
$person->save();

$data = [
    'name:en' => 'john doe',
    'email' => 'john@example.com'
];

$validator = Validator::make($data, [
    'name:en' => ['required', Rule::translatableUnique(Person::class, 'name:en')],
]);

```

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

### hasTranslation(?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Checks if the model has a translation in the default or given locale.

```APIDOC
## hasTranslation(?string $locale = null)

### Description
Checks if the model has a translation in the default or given locale.

### Method
`hasTranslation`

### Parameters
- **$locale** (?string) - Optional - The locale to check. Defaults to the current locale.

### Returns
- **bool** - True if a translation exists, false otherwise.

### Example
```php
$post->hasTranslation(); // true
$post->hasTranslation('fr'); // true
$post->hasTranslation('it'); // false
```
```

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

### translated scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns all posts with existing translations. Use this scope to retrieve only models that have at least one translation.

```php
Post::translated()->get();
```

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

### getDefaultLocale

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns the current default locale for the model, or null if none is set.

```php
$post->getDefaultLocale(); // null
```

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

### translations()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Eloquent relation method for the HasMany relation to the translation model.

```APIDOC
## translations()

### Description
Eloquent relation method for the HasMany relation to the translation model.

### Method
`translations`

### Returns
- **HasMany** - The relation instance.

### Example
```php
$post->translations; // collection of translations
```
```

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

### getCountryLocale(string $locale, string $country)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Returns the formatted country based locale.

```APIDOC
## getCountryLocale(string $locale, string $country)

### Description
Returns the formatted country based locale.

### Method
getCountryLocale

### Parameters
- **$locale** (string) - Required - The base locale
- **$country** (string) - Required - The country code

### Return Value
- **string** - The formatted country based locale
```

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

### withTranslation scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Eager loads the translation relationship only for the default and fallback (if enabled) locale. Use this to reduce queries when you need the translation for the current locale.

```php
Post::withTranslation()->get();
```

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

### getLanguageFromCountryBasedLocale(string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Returns the language locale from a country based locale.

```APIDOC
## getLanguageFromCountryBasedLocale(string $locale)

### Description
Returns the language locale from given country based locale.

### Method
getLanguageFromCountryBasedLocale

### Parameters
- **$locale** (string) - Required - The country based locale

### Return Value
- **string** - The language locale
```

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

### orWhereTranslationLike(string $translationField, $value, ?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Adds an OR clause to filter posts by checking the translation against a LIKE pattern.

```APIDOC
## orWhereTranslationLike(string $translationField, $value, ?string $locale = null)

### Description
Adds an OR clause to filter posts by checking the translation against a LIKE pattern.

### Method
Query Scope

### Parameters
- **$translationField** (string) - Required - The name of the translated attribute to filter on.
- **$value** (string) - Required - The LIKE pattern to match.
- **$locale** (?string) - Optional - The locale to filter by. Defaults to the current locale.

### Example
```php
Post::whereTranslationLike('title', '%first%')
    ->orWhereTranslationLike('title', '%second%')
    ->get();
```
```

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

### orderByTranslation(string $translationField, string $sortMethod = 'asc')

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Sorts the model by a given translation column value.

```APIDOC
## orderByTranslation(string $translationField, string $sortMethod = 'asc')

### Description
Sorts the model by a given translation column value.

### Method
Query Scope

### Parameters
- **$translationField** (string) - Required - The name of the translated attribute to sort by.
- **$sortMethod** (string) - Optional - The sort direction: 'asc' or 'desc'. Defaults to 'asc'.

### Example
```php
Post::orderByTranslation('title')->get();
```
```

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

### getTranslationsArray()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns all translations as an array, structured the same as accepted by the fill(array $data) method.

```APIDOC
## getTranslationsArray()

### Description
Returns all translations as an array, structured the same as accepted by the `fill(array $data)` method.

### Method
`getTranslationsArray`

### Returns
- **array** - An associative array of translations keyed by locale.

### Example
```php
$post->getTranslationsArray();
// Returns
[
 'en' => ['title' => 'My first post'],
 'de' => ['title' => 'Mein erster Beitrag'],
 'fr' => ['title' => 'Mon premier post'],
];
```
```

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

### Use TranslatableExists rule class for exists validation

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/custom-validation-rule.md

Use the TranslatableExists rule class directly to validate that a translatable attribute exists in the database. The rule will fail if the value does not exist.

```php
use Astrotomic\Translatable\Validation\Rules\TranslatableExists;
...

$person = new Person(['name' => 'john doe']);
$person->save();

$data = [
    'name' => 'john doe',
    'email' => 'john@example.com'
];
$validator = Validator::make($data, [
    'name' => ['required', new TranslatableExists(Person::class, 'name')],
]);

```

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

### orWhereTranslation scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Adds an OR condition to the whereTranslation scope. Use this to find posts where the translation field matches any of the given values.

```php
Post::whereTranslation('title', 'My first post')
    ->orWhereTranslation('title', 'My second post')
    ->get();
```

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

### orderByTranslation scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Sorts the model by a given translation column value. The sort method defaults to ascending; pass a second argument to change it.

```php
Post::orderByTranslation('title')->get()
```

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

### notTranslatedIn scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns all posts not translated in the given locale. Use this scope to filter models that lack a translation for the specified locale.

```php
Post::notTranslatedIn('en')->get();
```

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

### orWhereTranslationLike scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Adds an OR condition to the whereTranslationLike scope. Use this to find posts where the translation field matches any of the given LIKE patterns.

```php
Post::whereTranslationLike('title', '%first%')
    ->orWhereTranslationLike('title', '%second%')
    ->get();
```

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

### translatedIn scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns all posts translated in the given locale. Use this scope to filter models that have a translation for the specified locale.

```php
Post::translatedIn('en')->get();
```

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

### getTranslationsArray

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Returns all translations as an array structure accepted by the fill() method.

```php
$post->getTranslationsArray();
// Returns
[
 'en' => ['title' => 'My first post'],
 'de' => ['title' => 'Mein erster Beitrag'],
 'fr' => ['title' => 'Mon premier post'],
];
```

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

### whereTranslation scope

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Filters posts by checking the translation against the given value. Use this scope to find a post where the translation field matches exactly.

```php
Post::whereTranslation('title', 'My first post')->first();
```

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

### Use TranslatableUnique rule class for unique validation

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/custom-validation-rule.md

Use the TranslatableUnique rule class directly to validate that a translatable attribute is unique. The first argument is the model class, the second is the attribute name. The rule will fail if the value already exists in the database.

```php
use Astrotomic\Translatable\Validation\Rules\TranslatableUnique;
...

$person = new Person(['name' => 'john doe']);
$person->save();

$data = [
    'name' => 'john doe',
    'email' => 'john@example.com'
];
$validator = Validator::make($data, [
    'name' => ['required', new TranslatableUnique(Person::class, 'name')],
]);

```

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

### Customize empty translation property detection

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/fallback-locale.md

Override `isEmptyTranslatableAttribute()` in your model to customize how empty translation values are detected. The method receives the attribute key and value, and should return a boolean.

```php
protected function isEmptyTranslatableAttribute(string $key, $value): bool
{
    switch($key) {
        case 'name':
            return empty($value);
        case 'price':
            return !is_number($value);
        default:
            return is_null($value);
    }
}
```

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

### forget(string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Removes a locale from the available locales set.

```APIDOC
## forget(string $locale)

### Description
Removes the given locale from the available locales set. This method won't throw an exception if the locale isn't present.

### Method
forget

### Parameters
- **$locale** (string) - Required - The locale to remove

### Return Value
None
```

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

### static disableAutoloadTranslations()

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Disables autoloading of translations and returns parent attributes.

```APIDOC
## static disableAutoloadTranslations()

### Description
Disables autoloading of translations and returns parent attributes.

### Method
`disableAutoloadTranslations`

### Example
```php
Post::disableAutoloadTranslations();
```
```

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

### Update default locale via property assignment

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/forms.md

Update the default locale attributes by accessing the translatable attribute directly on the model.

```php
$post->title = 'My first post'; // Will update the English translatable model
```

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

### listsTranslations(string $translationField)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Returns an array containing pairs of post ids and the translated attribute value for the given field.

```APIDOC
## listsTranslations(string $translationField)

### Description
Returns an array containing pairs of post ids and the translated attribute value for the given field.

### Method
Query Scope

### Parameters
- **$translationField** (string) - Required - The name of the translated attribute to select.

### Example
```php
Post::listsTranslations('title')->get()->toArray();
```

### Response Example
```php
[
    ['id' => 1, 'title' => 'My first post'],
    ['id' => 2, 'title' => 'My second post']
]
```
```

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

### isLocaleCountryBased(string $locale)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/locales-helper.md

Checks if a given locale is a country specific locale.

```APIDOC
## isLocaleCountryBased(string $locale)

### Description
Checks if the given locale is a country specific locale.

### Method
isLocaleCountryBased

### Parameters
- **$locale** (string) - Required - The locale to check

### Return Value
- **bool** - True if the locale is country based, false otherwise
```

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

### Use Rule::translatableExists for locale-specific exists validation

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/custom-validation-rule.md

Use the Rule::translatableExists method to validate existence for a locale-specific attribute (e.g., 'name:en'). The method is called with the model class and the full attribute key including the locale. The rule will fail if the value does not exist for that locale.

```php
use Illuminate\Validation\Rule;
...

$person = new Person(['name' => 'john doe']);
$person->save();

$data = [
    'name:en' => 'john doe',
    'email' => 'john@example.com'
];

$validator = Validator::make($data, [
    'name:en' => ['required', Rule::translatableExists(Person::class, 'name:en')],
]);

```

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

### orWhereTranslation(string $translationField, $value, ?string $locale = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/scopes.md

Adds an OR clause to filter posts by checking the translation against the given value.

```APIDOC
## orWhereTranslation(string $translationField, $value, ?string $locale = null)

### Description
Adds an OR clause to filter posts by checking the translation against the given value.

### Method
Query Scope

### Parameters
- **$translationField** (string) - Required - The name of the translated attribute to filter on.
- **$value** (mixed) - Required - The value to compare against.
- **$locale** (?string) - Optional - The locale to filter by. Defaults to the current locale.

### Example
```php
Post::whereTranslation('title', 'My first post')
    ->orWhereTranslation('title', 'My second post')
    ->get();
```
```

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

### Saving translated attributes

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

Update a translated attribute for a specific locale and save the model.

```php
$post = Post::first();
echo $post->translate('en')->title; // My first post

$post->translate('en')->title = 'My cool post';
$post->save();

$post = Post::first();
echo $post->translate('en')->title; // My cool post
```

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

### hasTranslation

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Checks if the post has a translation in the default or given locale.

```php
$post->hasTranslation(); // true
$post->hasTranslation('fr'); // true
$post->hasTranslation('it'); // false
```

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

### Use Rule::translatableUnique for locale-specific unique validation

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/usage/custom-validation-rule.md

Use the Rule::translatableUnique method to validate uniqueness for a locale-specific attribute (e.g., 'name:en'). The method is called with the model class and the full attribute key including the locale. The rule will fail if the value already exists for that locale.

```php
use Astrotomic\Translatable\Validation\Rules\TranslatableUnique;
...

$person = new Person(['name' => 'john doe']);
$person->save();

$data = [
    'name:en' => 'john doe',
    'email' => 'john@example.com'
];

$validator = Validator::make($data, [
    'name:en' => ['required', Rule::translatableUnique(Person::class, 'name:en')],
]);

```

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

### deleteTranslations

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Deletes all translations for given locale(s); without parameters deletes all translations.

```php
$post->deleteTranslations(); // delete all translations
$post->deleteTranslations('de'); // delete german translation
$post->deleteTranslations(['de', 'en']); // delete german and english translation
```

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

### deleteTranslations(string|array $locales = null)

Source: https://github.com/astrotomic/laravel-translatable/blob/main/docs/package/methods.md

Deletes all translations for the given locale(s). If no locales are provided, deletes all translations.

```APIDOC
## deleteTranslations(string|array $locales = null)

### Description
Deletes all translations for the given locale(s). If no locales are provided, deletes all translations.

### Method
`deleteTranslations`

### Parameters
- **$locales** (string|array) - Optional - The locale(s) to delete. If null, all translations are deleted.

### Example
```php
$post->deleteTranslations(); // delete all translations
$post->deleteTranslations('de'); // delete german translation
$post->deleteTranslations(['de', 'en']); // delete german and english translation
```
```
Tokens:
Raw