README

Filament Translatable is a set of tools that help manage translations.

Installation

You can install the package via composer:

composer require filamerce/filament-translatable

Publish the assets:

php artisan filament:assets

Configuration

With spatie/laravel-translatable

The package from Spatie is the default supported way of handling translations. Follow the instructions in the README to properly configure your models.

With astrotomic/laravel-translatable

The package from Astrotomic is an alternative supported way of handling translations.

Follow the instructions to properly configure your models, but instead of using the Translatable trait from the Astrotomic package, please use Filamerce\FilamentTranslatable\Traits\AstrotomicTranslatable.

If you use the Astrotomic package, please configure the plugin to work in Astrotomic mode:

use Filamerce\FilamentTranslatable\Enums\TranslationMode;

FilamentTranslatablePlugin::make()
    ->translationMode(TranslationMode::Astrotomic)

You can also configure translationMode per component:

 Translations::make('translations')
    ->translationMode(TranslationMode::Astrotomic)

Or per field:

 TextInput::make('name')
    ->translatable()
    ->translationMode(TranslationMode::Astrotomic)

Setup

use Filamerce\FilamentTranslatable\FilamentTranslatablePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(FilamentTranslatablePlugin::make());
}

Setting translatable locales

To set up the locales that can be used to translate content, pass an array of locales to the locales() plugin method:

FilamentTranslatablePlugin::make()
     ->locales(['en', 'pl', 'fr']),

You can set locale labels using key => value array:

FilamentTranslatablePlugin::make()
    ->locales([
        'pl' => __('Polish'),
        'en' => __('English')
    ])

Also, you can pass a Closure:

FilamentTranslatablePlugin::make()
    ->locales(fn () => Language::pluck('code', 'name'))

Setting default locale

You can set the default locale using the defaultLocale() method:

FilamentTranslatablePlugin::make()
     ->defaultLocale('pl'),

Enable or disable flags in locale labels

You can enable or disable flags in locale labels (disabled by default):

FilamentTranslatablePlugin::make()
    ->displayFlagsInLocaleLabels(true)

Setting flag width

You can set the flag width using:

FilamentTranslatablePlugin::make()
    ->flagWidth('24px')

Enable or disable names in locale labels

You can enable or disable locale names in locale labels (enabled by default):

FilamentTranslatablePlugin::make()
    ->displayNamesInLocaleLabels(false)

Otherwise, the config value app.locale will be used.

This affects several methods that can be used on fields.

Usage

translatable() macro

By using the translatable() macro, you can quickly configure a single form field to support multiple languages and provide translations for each locale.

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->translatable()

Marking field as required for specified locale

This way, the "name" field will only be required in the "en" language.

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->requiredLocale('en')
    ->translatable()

Marking field as required for default locale

This way, the "name" field will only be required in the default language.

use Filament\Forms\Components\TextInput;

TextInput::make('name')
    ->requiredDefaultLocale()
    ->translatable()

Decorating language specified fields

You can fully customize language-specific fields using the decorateTranslationField() method.

use Filament\Forms\Components\TextInput;

TextInput::make('price')
    ->decorateTranslationField('pl', fn (TextInput $field) => $field->suffix('PLN'))
    ->decorateTranslationField('en', fn (TextInput $field) => $field->prefix('USD')),
    ->translatable()

Customizing Translations component

After using the translatable() method, the context of the field is switched to the Translations component, so you can use any method that belongs to the component.

use Filament\Forms\Components\TextInput;

TextInput::make('price')
    ->requiredDefaultLocale()
    ->translatable() // Here context is switched from TextInput to Translations component
    ->vertical()
    ->displayFlagsInLocaleLabels(true)
    ->displayNamesInLocaleLabels(false)
    ->flagWidth('48px')

Caution

Be sure to set field-specific methods like required() or requiredDefaultLocale() before calling the translatable() method.

Translations component

By using the Translations component, you can easily configure your form fields to support multiple languages and provide translations for each locale.

use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make('translations') // name is required to properly handle actions
    ->schema([
        TextInput::make('name')
    ])

Note

Using the translatable() method within the Translations component is not needed.

Important

Be sure to set different names for each Translations component when using multiple instances.

Setting the translatable locales for a particular fields

By default, the translatable locales can be set globally for all translation form components in the plugin configuration. Alternatively, you can customize the translatable locales for a particular resource by overriding the locales() method in the Translate class:

Translations::make('translations')
    ->locales(['en', 'es'])

Setting the translatable label for a particular field

You have the flexibility to customize the translation label for each field in each locale. You can use the fieldTranslatableLabel() method to provide custom labels based on the field instance and the current locale.

use Filamerce\FilamentTranslatable\Forms\Component\Translations;

 Translations::make()
    ->schema([
        // Fields
    ])
    ->fieldTranslatableLabel(fn ($field, $locale) => __($field->getName(), locale: $locale))

Adding prefix/suffix locale label to the field

If you want to add a prefix or suffix locale label to the form field, you can use the prefixLocaleLabel() or suffixLocaleLabel() method. This makes it easier for users to identify the language associated with each field.

use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make('translations')
    ->schema([
        // Fields
    ])
    ->prefixLocaleLabel()
    ->suffixLocaleLabel()

Setting the locale display name

By default, the prefix/suffix locale display name is generated from the locale code and enclosed in parentheses, "()". You may customize this using the preformLocaleLabelUsing() method:

use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make('translations')
    ->preformLocaleLabelUsing(fn (string $locale, string $label) => "[{$label}]");

Injecting the current form field

Additionally, if you need to access the current form field instance, you can inject the $field parameter into the callback functions. This allows you to perform specific actions or apply conditions based on the field being processed.

use Filament\Forms\Components\Component;
use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make('translations')
    // ...
    ->prefixLocaleLabel(function(Component $field) {
        // need return boolean value
        return $field->getName() == 'title';
    })
    ->suffixLocaleLabel(function(Component $field) {
        // need return boolean value
        return $field->getName() == 'title';
    })

Adding action

You may add actions before each container of child components using the actions() method:

use Filament\Forms\Components\Actions\Action;
use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make('translations')
    ->actions([
        Action::make('fillDumpTitle')
    ])

Injecting the locale on current child container

If you wish to access the locale that has been passed to the action, define an $arguments parameter and get the value of locale from $arguments:

use Filament\Forms\Components\Actions\Action;
use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make()
    ->actions([
        Action::make('fillDumpTitle')
            ->action(function (array $arguments) {
                $locale = $arguments['locale'];
                // ...
            })
    ])

Injecting the locale to form field

If you wish to access the current locale instance for the field, define a $locale parameter:

use Filament\Forms\Components\TextInput;
use Filamerce\FilamentTranslatable\Forms\Component\Translations;

Translations::make()
    ->schema(fn (string $locale) => [TextInput::make('title')->required($locale == 'en')])

Removing the styled container

By default, the translate component and its content are wrapped in a container styled as a card. You may remove the styled container using contained():

use Filamerce\FilamentTranslatable\Forms\Component\Translations;
 
Translations::make()
    ->contained(false)

Vertical tabs

You can display translations as vertical tabs:

use Filamerce\FilamentTranslatable\Forms\Component\Translations;
 
Translations::make()
    ->vertical()

Changing plugin settings

You can customize plugin settings directly on the component:

use Filamerce\FilamentTranslatable\Forms\Component\Translations;
 
Translations::make()
    ->displayNamesInLocaleLabels(false)
    ->displayFlagsInLocaleLabels(true)
    ->flagWidth('48px')

Exclude

The exclude feature allows you to specify fields that you don't want to include in the translation process. This can be useful for fields that contain dynamic content or that shouldn't be translated into other languages.

use Filamerce\FilamentTranslatable\Forms\Component\Translations;
 
Translations::make('translations')
    ->schema([
        Forms\Components\TextInput::make('title'),
        Forms\Components\TextInput::make('description'),
    ])
    ->exclude(['description'])

Without exclude:

{
    "title": {
        "en": "Dump",
        "es": "Dump",
        "fr": "Dump"
    },
    "description": {
        "en": null,
        "es": null,
        "fr": null
    }
}

With exclude:

{
    "title": {
        "en": "Dump",
        "es": "Dump",
        "fr": "Dump"
    },
    "description": null
}

Publishing Views

To publish the views, run:

php artisan vendor:publish --provider="Filamerce\\FilamentTranslatable\\FilamentTranslatableProvider" --tag="filament-translatable-views"

Testing

composer test

Changelog

See the CHANGELOG for more information on what has changed recently.

Contributing

See CONTRIBUTING for details.

Security Vulnerabilities

If you discover any security-related issues, please email code@webard.me instead of using the issue tracker.

Credits

• Lipis for icons
• Solution Forest for great inspiration
• Outer Web for the macro idea
• All Contributors

License

Filament Translatable is open-sourced software licensed under the MIT license.