Download the PHP package happenv-com/filament-translatable without Composer

Filament Translatable

Filament Translatable is a flexible package that provides a complete solution for managing multilingual content in Filament admin panels. It allows you to easily create translatable form fields with an intuitive tabbed interface, supporting multiple locales and translation packages.

Key features

• Multiple translation backends — supports both spatie/laravel-translatable and astrotomic/laravel-translatable
• Two usage modes — use the quick translatable() macro on any field, or the full Translations component for advanced scenarios
• Locale tabs with flags — display translations in horizontal or vertical tabs with optional country flag icons
• Flexible locale configuration — define locales globally or per-component, with custom labels
• Required locale validation — mark fields as required for specific locales or only for the default locale
• Field decoration per locale — customize field appearance (prefix, suffix, etc.) for each language
• Custom actions per tab — add custom Filament actions to each locale tab with access to the current locale
• Include or exclude fields from translation — selectively control which fields are translated
• Prefix/suffix locale labels — optionally add locale indicators to field labels

Requirements

Translations are stored by spatie/laravel-translatable (default) or astrotomic/laravel-translatable — install the one you use.

Filament 3 is not supported by any version of this package.

Installation

You can install the package via composer:

Publish the assets:

Optionally, register the plugin in your panel provider to configure the package per panel (see Where settings come from):

Configuration

Translation backends

With spatie/laravel-translatable

The Spatie package is the default translation backend. Follow the instructions in the Spatie documentation to properly configure your models.

With astrotomic/laravel-translatable

The Astrotomic package is an alternative translation backend.

Follow the Astrotomic documentation to configure your models using the original Astrotomic\Translatable\Translatable trait — no custom trait is needed. The component loads each locale's value from the record itself and saves it using Astrotomic's title:en attribute format.

When using the Astrotomic package, configure the plugin to use Astrotomic mode:

You can also configure translationMode per component:

Or per field (after translatable() you configure the Translations component):

translationMode() accepts TranslationMode::Spatie, TranslationMode::Astrotomic or your own implementation of Happenv\FilamentTranslatable\Drivers\TranslationDriver.

Where settings come from

The plugin is optional — the Translations component also works in plain Livewire components and in panels without the plugin. Settings are resolved from weakest to strongest:

1. Package defaults: app.fallback_locale as the only locale and the default locale, Spatie mode, locale names shown, flags hidden, 24px flags.
2. The plugin registered on the current panel.

3. Translations::configureUsing(), e.g. in a service provider:

4. Methods called on the component instance.

Every setting accepts a value or a Closure.

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:

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

Also, you can pass a Closure:

Setting default locale

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

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

Enable or disable flags in locale labels

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

Setting flag width

You can set the flag width using:

Enable or disable names in locale labels

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

Publishing the views

To publish the views, run:

Usage

translatable() macro

The translatable() macro allows you to quickly convert any form field into a multilingual field that supports translations for each configured locale.

Marking a field as required for a specific locale

You can make a field required only for specific locales. In this example, the "name" field will only be required for the English language:

Marking a field as required for the default locale

You can make a field required only for the default locale. The default locale is determined by the defaultLocale() setting or the app.fallback_locale config value:

Both requiredLocale() and requiredDefaultLocale() accept a condition as a boolean or a Closure:

Decorating language-specific fields

You can customize the appearance of fields for specific locales using the decorateTranslationField() method. This is useful for adding locale-specific prefixes, suffixes, or other modifications. The decorator can also receive the locale code as $locale:

Passing options to translatable()

Use named arguments to set the locales or configure the generated Translations component:

When locales is omitted, the locales configured by the plugin or configureUsing() are used.

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.

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

Translations component

The Translations component provides a more powerful way to configure multiple form fields for multilingual support. It displays translations in a tabbed interface, with each tab representing a different locale.

[!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 specific components

By default, locales are configured globally in the plugin settings. However, you can override the locales for a specific Translations component:

Setting custom field labels per locale

You can customize field labels for each locale using the fieldTranslatableLabel() method. This is useful for translating field labels themselves. In all closures of this package $locale is the locale code (a string):

Adding prefix/suffix locale labels to fields

You can add the locale name as a prefix or suffix to field labels using the prefixLocaleLabel() or suffixLocaleLabel() methods. This helps users identify which language they are editing:

Customizing the locale label format

By default, the prefix/suffix locale label is the locale label enclosed in parentheses (e.g., "(English)"). You can customize this format using the formatLocaleLabelUsing() method:

Conditionally adding locale labels

You can conditionally add prefix/suffix labels by injecting the $field parameter into the callback. This allows you to apply locale labels only to specific fields:

Adding actions to locale tabs

You can add custom Filament actions to each locale tab using the actions() method. Actions appear in the tab header and can be used for operations like auto-translation or copying content between locales:

Accessing the locale in actions

To access the current locale within an action, use the $arguments parameter and retrieve the locale value:

Accessing the locale in schema

You can access the current locale within the schema definition by defining a $locale parameter. This is useful for conditional logic based on the locale:

Removing the styled container

By default, the Translations component is wrapped in a card-styled container. You can remove this styling using the contained() method:

Vertical tabs

You can display translations as vertical tabs:

Overriding plugin settings per component

You can override the global plugin settings directly on individual components:

Excluding fields from translation

The exclude() method allows you to specify fields that should not be translated. Excluded fields will appear in the form but will not be duplicated for each locale. This is useful for fields that contain non-translatable content:

Without exclude:

With exclude:

Including only specific fields for translation

The include() method allows you to specify which fields should be translated. This is useful when only a small subset of fields in a large form requires translations.

Without include:

With include(['title']):

Development

The package's stylesheet is built by the Tailwind CLI from resources/css/app.css — with the utilities used in resources/views and src — into resources/dist, which is committed. After changing any of them, rebuild and commit the result — CI refuses outdated assets:

Upgrading

Breaking changes and how to migrate are described in UPGRADING for every major version. Upgrading from 4.x? Start there.

Changelog

See GitHub releases for what has changed recently.

Contributing

See CONTRIBUTING for details.

Security vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Happenv sp. z o.o.
• webard
• Lipis for icons
• Solution Forest for great inspiration
• Outer Web for the macro idea
• All contributors

License

The MIT License (MIT). See License File for more information.