astrotomic/laravel-translatable

The \Astrotomic\Translatable\Locales class is a singleton service that manages all locales available for translation. It can be accessed via the translatable.locales service container binding or by instantiating the class directly. It implements ArrayAccess, allowing it to be used like a standard array.

Use this helper to check for, add, or remove locales at runtime without needing to modify the underlying configuration file.

When a translation for a country-specific locale (like es-MX) is missing, the package follows a hierarchical fallback pattern:

1. It first attempts to find a translation for the base language (e.g., es).
2. If no base language translation is found, it then falls back to the global fallback_locale (e.g., en).

Example: If searching for es-MX fails, it checks es, then en.

The package relies on a set of protected methods that are considered part of its stable contract. Changes to these methods will trigger a major release. If you are extending the package's core functionality, be aware of these internal lifecycle methods:

• isEmptyTranslatableAttribute(string $key, $value): bool: Detects if a specific translation attribute value is considered empty.
• saveTranslations(): bool: Handles the persistence of all currently attached translations.

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;
}

Install the package via Composer to add multilingual support to your Laravel models.

composer require astrotomic/laravel-translatable

When validating translated attributes, manually listing rules for every locale is complex. The RuleFactory class simplifies this by allowing you to use placeholders (e.g., %title%) in your rule keys. The factory automatically expands these placeholders into full dot-notation or colon-separated keys for all configured locales, including updating any rule strings (like required_with) to match the new locale-specific keys.

Example usage:

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

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

First, publish the configuration file:

php artisan vendor:publish --tag=translatable

Then, define the locales your application should use in the published config file. You can use simple strings or nested arrays for specific regional variations (e.g., Mexican Spanish).

There is no strict format for locale names; you can use any identifier (like en, eng, or es) as long as you are consistent.

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

Alternatively, you can use colon notation for your input names. In this syntax, the attribute name comes first, followed by the locale. This is another way to structure requests that can be handled by the package.

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

To translate multiple fields across different locales in a single operation, use the overridden fill() method. This method accepts an associative array where the first level of keys represents the locales, and the second level contains the translated attributes for that specific locale.

This approach is ideal for multi-language forms where you want to save all translations at once.

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