filamerce / filament-translatable
Highly customizable Translation component for FilamentPHP.
Requires
- php: ^8.2
- filament/filament: ^4.0
Requires (Dev)
- astrotomic/laravel-translatable: ^11.16
- larastan/larastan: ^3.0
- laravel/pint: ^1.0
- orchestra/testbench: ^9.14|^10.0
- pestphp/pest: ^3.0
- pestphp/pest-plugin-laravel: ^3.0
- pestphp/pest-plugin-livewire: ^3.0
Suggests
- astrotomic/laravel-translatable: Alternative way for handling translations in Laravel using separate database tables.
- spatie/laravel-translatable: For handling translations in Laravel using JSON fields.
README
Filament Translatable is a set of tools that help manage translations.
Installation
Filament Version | Filament Translate Field Version |
---|---|
v4.x | v2.x |
v4.x | v3.x |
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.