novius / laravel-filament-translatable
A Laravel Filament package for translatable fields
Package info
github.com/novius/laravel-filament-translatable
pkg:composer/novius/laravel-filament-translatable
Fund package maintenance!
Requires
- php: >=8.2
- filament/filament: ^4.0 | ^5.0
- novius/laravel-translatable: ^2.1
Requires (Dev)
- larastan/larastan: ^3.1
- laravel/pint: ^1.21
- novius/laravel-publishable: ^3.1
- orchestra/testbench: ^9.0 | ^10.1 | ^11.0
- pestphp/pest: ^3.7
- phpstan/extension-installer: ^1.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Introduction
This package allows you to manage Laravel Models that use Laravel Translatable in Laravel Filament.
Requirements
- Laravel Filament >= 4
- Laravel >= 11.0 (tested with Laravel 12 and 13)
- PHP >= 8.2
Installation
You can install the package via composer:
composer require novius/laravel-filament-translatable
Assets
Next we need to publish the package's assets. We do this by running the following command:
php artisan vendor:publish --provider="Novius\LaravelFilamentTranslatable\LaravelFilamentTranslatableServiceProvider" --tag="public"
Lang files
If you want to customize the lang files, you can publish them with:
php artisan vendor:publish --provider="Novius\LaravelFilamentTranslatable\LaravelFilamentTranslatableServiceProvider" --tag="lang"
Locale Filter
Add the LocaleFilter filter on your Filament Resource.
use Filament\Resources\Resource; use Novius\LaravelFilamentTranslatable\Filament\Tables\Filters\LocaleFilter; class Post extends Resource { public static function table(Table $table): Table { return $table /// ... ->filters([ LocaleFilter::make('locale'), /// ... ]); } }
Locale Column
Add the LocaleColumn column on your Filament Resource.
use Filament\Resources\Resource; use Novius\LaravelFilamentTranslatable\Filament\Tables\Columns\LocaleColumn; class Post extends Resource { public static function table(Table $table): Table { return $table /// ... ->columns([ /// ... LocaleColumn::make('locale'), ]); } }
Locale Input
Add the Locale input on your Filament Resource.
use Filament\Resources\Resource; use Novius\LaravelFilamentTranslatable\Filament\Forms\Components\Locale; class Post extends Resource { public static function form(Form $form): Form { return $form ->schema([ // ... Locale::make('locale') ->required(), // ... ]); } }
Translations Column and features
In your Filament Resource.
use Filament\Resources\Resource; use Novius\LaravelFilamentTranslatable\Filament\Tables\Columns\TranslationsColumn; class Post extends Resource { public static function form(Form $form): Form { return $form ->schema([ Hidden::make('locale_parent_id'), ]); } public static function form(Form $form): Form { return $table // ... ->columns([ // ... TranslationsColumn::make('translations') ->locales(['de', 'en']) // Optional. Restricted the locals displayed on this list ->flagWidth(16) // Optional. Width in pixel of the flags ->onlyMissing() // Optional. Will display only translations missing ->withoutMissing() // Optional. Will display only existing translations , // ... ]); } }
Each flag links to the translation, on its edit page (or its view page when the user cannot edit it), or to the create page for a missing translation when the user can create: without access, the flag has no link.
And declare your Create page like this :
<?php use Illuminate\Database\Eloquent\Model; use Illuminate\Support\Str; use LaravelLang\Locales\Facades\Locales; use Novius\LaravelFilamentPageManager\Filament\PageManagerPlugin; use Novius\LaravelFilamentTranslatable\Filament\Resources\Pages\CreateRecord; class CreatePost extends CreateRecord { public static function getResource(): string { return PageManagerPlugin::getPlugin()->getResource('PostResource'); } protected function getDataFromTranslate(Model $parent, string $locale): array { // The attributes of copiedOnTranslate(), as a draft for a publishable model $data = parent::getDataFromTranslate($parent, $locale); // Modify data according the parent $data['title'] = $parent->title.' '.Locales::get($locale)->native; $data['slug'] = Str::slug($data['title']); return $data; } }
By default, a translation gets all the attributes of its parent. List the attributes to copy instead with
copiedOnTranslate():
class CreatePost extends CreateRecord { protected function copiedOnTranslate(): ?array { return ['title', 'content']; } }
Do not copy a unique attribute (a slug) as is: leave it out of copiedOnTranslate(), or compute it in
getDataFromTranslate() as above.
A translation of a publishable model (Publishable trait of
Laravel Publishable) starts as a draft, without the publication dates of
its parent: it is not published before being reviewed. To copy the publication of the parent instead:
class CreatePost extends CreateRecord { protected function translationStartsAsDraft(): bool { return false; } }
Translations Action Group
On the view or edit page of a translatable model, a Translations dropdown button opens the other translations of the
record, then creates the missing ones with the create page of the package (see above). Use the
HasTranslationsActionGroup trait and place translationsActionGroup() in the header actions:
use Filament\Actions\DeleteAction; use Filament\Resources\Pages\EditRecord; use Novius\LaravelFilamentTranslatable\Filament\Resources\Pages\Concerns\HasTranslationsActionGroup; class EditPost extends EditRecord { use HasTranslationsActionGroup; protected function getHeaderActions(): array { return [ $this->translationsActionGroup(), DeleteAction::make(), ]; } }
Outside of such a page, build the group of a model with TranslationsActionGroup::forModel(Post::class). It is an
ActionGroup of Filament: customize it as one (->label(), ->icon(), ->iconButton(), ...).
- An existing translation opens on the view page from a view page, on the edit page otherwise, or on the other one when the user cannot access the first. A deleted translation (soft deletes) is marked as such.
- A missing translation is offered when the resource has a create page and the user can create.
- The locale of the record is not listed. The group is hidden for a model with less than two locales, or when it has nothing to offer.
- The flags are the published assets of the package (see Assets).
Common record
For a model whose data shared by all the locales is held by a common record (HasCommonRecord and IsCommonRecord of
Laravel Translatable), the resource is the one of the translatable
model (Product), and the CommonRecordSection holds the fields of the common record (ProductCommon), bound to its
commonRecord relationship:
use Filament\Forms\Components\Hidden; use Filament\Forms\Components\TextInput; use Novius\LaravelFilamentTranslatable\Filament\Forms\Components\CommonRecordSection; use Novius\LaravelFilamentTranslatable\Filament\Forms\Components\Locale; class ProductResource extends Resource { public static function form(Schema $schema): Schema { return $schema->components([ TextInput::make('title')->required(), Locale::make('locale')->required(), Hidden::make('locale_parent_id'), CommonRecordSection::make()->schema([ TextInput::make('reference')->required(), // ... the fields of the common record ]), ]); } }
With the CreateRecord page of the package:
- Creating an original saves the common record from the fields of the section first, then the original with its key,
in a database transaction: the common record gets every value of the form, required ones included, and
createCommonRecord()of the model is not called. The fields of the common record can be split into severalCommonRecordSection(CommonRecordSection::make('Logistics')), saved together. - A hidden or disabled section (
->hiddenOn('create'), for instance) is not saved: the model creates its common record withcreateCommonRecord(), and the section edits it once the original is created. - Creating a translation shares the common record of its parent: the section shows a notice instead of its fields, and saves nothing.
- Editing a translation updates the common record, so all the translations.
Warning
A group of translations created before HasCommonRecord was added to the model has no common record. Editing one of
its translations with a CommonRecordSection creates a common record for this translation only, which
laravel-translatable refuses (a TranslatableException, common_record_mismatch). A model not translated yet simply
gets its common record. Give a common record to the existing groups (a migration) before adding the section.
Testing
Run the linter, the static analysis and the tests with:
composer test
Lint
Lint your code with Laravel Pint using:
composer lint
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Contributions are welcome! Please see CONTRIBUTING for details.
Licence
This package is under GNU Affero General Public License v3 or (at your option) any later version.