Filament Translatable

https://github.com/jeffersongoncalves/filament-translatable
Admin
Filament Translatable is an enhanced Laravel Filament plugin for spatie/laravel-translatable...
Tokens:6,573
Snippets:60
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install dependencies and run tests, PHPStan, and Pint

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/CLAUDE.md

Commands for installing dependencies, running tests with Pest, performing PHPStan analysis, and formatting code with Pint. Use these in the project root after cloning the repository.

```bash
"/c/Users/simao/.config/herd/bin/composer.bat" install
```

```bash
"/c/Users/simao/.config/herd/bin/php.bat" vendor/bin/pest
```

```bash
"/c/Users/simao/.config/herd/bin/php.bat" vendor/bin/phpstan analyse
```

```bash
"/c/Users/simao/.config/herd/bin/php.bat" vendor/bin/pint
```

--------------------------------

### Install via Composer

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Install the package via Composer. Requires version ^3.0.

```bash
composer require jeffersongoncalves/filament-translatable:"^3.0"
```

--------------------------------

### Migration with JSON Translatable Columns

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Migration example showing that translatable columns must use the json column type, while non-translatable fields use regular types.

```php
Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->json('title');
    $table->json('content');
    $table->string('slug'); // non-translatable fields use regular column types
    $table->timestamps();
});
```

--------------------------------

### Replace package with composer

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Replace the official Filament translatable plugin with this enhanced fork. Run these commands in your project root to remove the old package and install the new one.

```bash
composer remove filament/spatie-laravel-translatable-plugin
composer require jeffersongoncalves/filament-translatable:"^3.0"
```

--------------------------------

### Check translation status with HasTranslationStatus trait

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/resources/boost/skills/filament-translatable-development/SKILL.md

Use the HasTranslationStatus trait to programmatically check translation status. Provides methods to get per-locale status, completeness percentage, and translated locales for a record.

```php
use JeffersonGoncalves\FilamentTranslatable\Concerns\HasTranslationStatus;

// Methods available:
$this->getTranslationStatus($record);       // ['en' => 'complete', 'fr' => 'empty']
$this->getTranslationCompleteness($record);  // ['en' => 100, 'fr' => 0]
$this->getTranslatedLocales($record);         // ['en', 'pt_BR']
```

--------------------------------

### Publish Config

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Optionally publish the package configuration file.

```bash
php artisan vendor:publish --tag="filament-translatable-config"
```

--------------------------------

### Add Translatable to Create, Edit, and List Pages

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Add the appropriate Translatable trait and LocaleSwitcher header action to Create, Edit, and List pages.

```php
use JeffersonGoncalves\FilamentTranslatable\Actions\LocaleSwitcher;
use JeffersonGoncalves\FilamentTranslatable\Resources\Pages\CreateRecord;
use JeffersonGoncalves\FilamentTranslatable\Resources\Pages\EditRecord;
use JeffersonGoncalves\FilamentTranslatable\Resources\Pages\ListRecords;

class CreatePost extends CreateRecord
{
    use CreateRecord\Concerns\Translatable;

    protected function getHeaderActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}

class EditPost extends EditRecord
{
    use EditRecord\Concerns\Translatable;

    protected function getHeaderActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}

class ListPosts extends ListRecords
{
    use ListRecords\Concerns\Translatable;

    protected function getHeaderActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}
```

--------------------------------

### Configure filament-translatable.php with locale flags and status colors

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Configuration file for the filament-translatable package. Defines locale flags as emoji Unicode escapes, the flag display format (options: 'flag_and_label', 'flag_only', 'label_only'), and Filament color names for translation status badges ('complete', 'partial', 'empty').

```php
// config/filament-translatable.php

return [
    /*
    |--------------------------------------------------------------------------
    | Locale Flags
    |--------------------------------------------------------------------------
    |
    | Map of locale codes to emoji flags. Used by the LocaleSwitcher and
    | TranslationStatusColumn to display visual locale indicators.
    |
    */
    'locale_flags' => [
        'en' => "\u{1F1FA}\u{1F1F8}", // US
        'pt_BR' => "\u{1F1E7}\u{1F1F7}", // BR
        'es' => "\u{1F1EA}\u{1F1F8}", // ES
        'fr' => "\u{1F1EB}\u{1F1F7}", // FR
        'de' => "\u{1F1E9}\u{1F1EA}", // DE
        // ... 25+ more built-in
    ],

    /*
    |--------------------------------------------------------------------------
    | Flag Display Format
    |--------------------------------------------------------------------------
    |
    | Controls how locale labels are displayed in the LocaleSwitcher.
    | Options: 'flag_and_label', 'flag_only', 'label_only'
    |
    */
    'flag_display' => 'flag_and_label',

    /*
    |--------------------------------------------------------------------------
    | Translation Status Colors
    |--------------------------------------------------------------------------
    |
    | Filament color names used by the TranslationStatusColumn badges.
    |
    */
    'status_colors' => [
        'complete' => 'success',
        'partial' => 'warning',
        'empty' => 'danger',
    ],
];
```

--------------------------------

### Register Plugin in PanelProvider

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Register the plugin in your PanelProvider and set default locales.

```php
use JeffersonGoncalves\FilamentTranslatable\FilamentTranslatablePlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentTranslatablePlugin::make()
                ->defaultLocales(['en', 'pt_BR', 'es']),
        ]);
}
```

--------------------------------

### Update PanelProvider imports

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Update the PanelProvider imports to use the new plugin class. Replace the old import with the new one as shown.

```php
// Before
use Filament\SpatieLaravelTranslatablePlugin;

// After
use JeffersonGoncalves\FilamentTranslatable\FilamentTranslatablePlugin;
```

--------------------------------

### Configure Model with HasTranslations

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Configure your Eloquent model to use Spatie's HasTranslations trait and define translatable attributes.

```php
use Illuminate\Database\Eloquent\Model;
use Spatie\Translatable\HasTranslations;

class Post extends Model
{
    use HasTranslations;

    protected $fillable = ['title', 'content', 'slug'];

    public array $translatable = ['title', 'content'];
}
```

--------------------------------

### Add Translatable to View and Manage Pages

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Add Translatable traits and LocaleSwitcher to ViewRecord and ManageRecords pages for additional page types.

```php
use JeffersonGoncalves\FilamentTranslatable\Resources\Pages\ViewRecord;
use JeffersonGoncalves\FilamentTranslatable\Resources\Pages\ManageRecords;

// ViewRecord
class ViewPost extends ViewRecord
{
    use ViewRecord\Concerns\Translatable;

    protected function getHeaderActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}

// ManageRecords (simple resource)
class ManagePosts extends ManageRecords
{
    use ManageRecords\Concerns\Translatable;

    protected function getHeaderActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}
```

--------------------------------

### Configure FilamentTranslatablePlugin with locales and flags

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/resources/boost/skills/filament-translatable-development/SKILL.md

Configure the FilamentTranslatablePlugin with default locales, locale flags, flag display mode, and a custom label resolver. The getLocaleLabelUsing closure maps locale codes to display labels, returning null for unknown locales.

```php
use JeffersonGoncalves\FilamentTranslatable\FilamentTranslatablePlugin;

FilamentTranslatablePlugin::make()
    ->defaultLocales(['en', 'pt_BR', 'es'])
    ->localeFlags(['en' => '🇺🇸', 'pt_BR' => '🇧🇷', 'es' => '🇪🇸'])
    ->flagDisplay('flag_and_label')
    ->getLocaleLabelUsing(fn (string $locale) => match ($locale) {
        'en' => 'English',
        'pt_BR' => 'Portugues',
        'es' => 'Espanol',
        default => null,
    });
```

--------------------------------

### Model requirements with HasTranslations trait

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/resources/boost/skills/filament-translatable-development/SKILL.md

Model must use Spatie's HasTranslations trait and define the translatable attributes in the $translatable array. This is a prerequisite for the plugin to work.

```php
use Spatie\Translatable\HasTranslations;

class Post extends Model
{
    use HasTranslations;

    public array $translatable = ['title', 'content'];
}
```

--------------------------------

### Configure locale flags with FilamentTranslatablePlugin

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Configure locale flags for the Filament Translatable plugin. The `localeFlags` method maps each locale to an emoji flag, and `flagDisplay` controls whether to show the flag, label, or both. Built-in flags are available for 30+ locales.

```php
FilamentTranslatablePlugin::make()
    ->defaultLocales(['en', 'pt_BR', 'es'])
    ->localeFlags([
        'en' => "\u{1F1FA}\u{1F1F8}",
        'pt_BR' => "\u{1F1E7}\u{1F1F7}",
        'es' => "\u{1F1EA}\u{1F1F8}",
    ])
    ->flagDisplay('flag_and_label'), // 'flag_and_label' | 'flag_only' | 'label_only'
```

--------------------------------

### Update LocaleSwitcher imports

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Update LocaleSwitcher imports. Use the Actions namespace for pages and the Tables\Actions namespace for relation managers.

```php
// Before
use Filament\Actions\LocaleSwitcher;

// After (for pages)
use JeffersonGoncalves\FilamentTranslatable\Actions\LocaleSwitcher;

// After (for relation managers)
use JeffersonGoncalves\FilamentTranslatable\Tables\Actions\LocaleSwitcher;
```

--------------------------------

### Add Translatable to Resource

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Add the Translatable concern to your Filament resource.

```php
use JeffersonGoncalves\FilamentTranslatable\Resources\Concerns\Translatable;

class PostResource extends Resource
{
    use Translatable;

    // ...
}
```

--------------------------------

### Add TranslationStatusColumn to Filament table

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Adds a translation status column to a Filament table. The column shows colored badges per locale, with options to display completion percentage, hide fully translated locales, show emoji flags, and override the plugin's default locales.

```php
use JeffersonGoncalves\FilamentTranslatable\Tables\Columns\TranslationStatusColumn;

public static function table(Table $table): Table
{
    return $table->columns([
        TextColumn::make('title'),
        TranslationStatusColumn::make('translations')
            ->showPercentage()    // show completion percentage
            ->onlyShowMissing()   // hide locales that are fully translated
            ->showFlags()         // show emoji flags next to locale labels
            ->locales(['en', 'pt_BR', 'es']), // override plugin locales
    ]);
}
```

--------------------------------

### Override locale labels with getLocaleLabelUsing

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Override the display name for each locale using `getLocaleLabelUsing`. The closure receives the locale string and returns a custom label; returning `null` falls back to `locale_get_display_name()`.

```php
FilamentTranslatablePlugin::make()
    ->defaultLocales(['en', 'pt_BR'])
    ->getLocaleLabelUsing(fn (string $locale) => match ($locale) {
        'en' => 'English',
        'pt_BR' => 'Portugues',
        default => null, // falls back to locale_get_display_name()
    }),
```

--------------------------------

### Use TranslationStatusColumn in table

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/resources/boost/skills/filament-translatable-development/SKILL.md

Add a TranslationStatusColumn to a table to display translation completeness. Options include showing percentage, filtering to missing translations, showing locale flags, and specifying which locales to check.

```php
use JeffersonGoncalves\FilamentTranslatable\Tables\Columns\TranslationStatusColumn;

TranslationStatusColumn::make('translations')
    ->showPercentage()
    ->onlyShowMissing()
    ->showFlags()
    ->locales(['en', 'pt_BR'])
```

--------------------------------

### Use InteractsWithTranslations trait in EditRecord

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Use the unified InteractsWithTranslations trait instead of page-specific traits to reduce boilerplate. It automatically detects the page type and provides getTranslatableLocales() and locale management.

```php
use JeffersonGoncalves\FilamentTranslatable\Concerns\InteractsWithTranslations;

class EditPost extends EditRecord
{
    use InteractsWithTranslations;

    // Automatically detects the page type and provides
    // getTranslatableLocales() and locale management
}
```

--------------------------------

### Add LocaleSwitcher to a RelationManager

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Add independent locale management to a relation manager by using the `Translatable` concern and adding a `LocaleSwitcher` header action. Note that relation managers use `Tables\Actions\LocaleSwitcher`, while pages use `Actions\LocaleSwitcher`.

```php
use JeffersonGoncalves\FilamentTranslatable\Resources\RelationManagers\Concerns\Translatable;
use JeffersonGoncalves\FilamentTranslatable\Tables\Actions\LocaleSwitcher;

class CommentsRelationManager extends RelationManager
{
    use Translatable;

    protected function getHeaderActions(): array
    {
        return [LocaleSwitcher::make()];
    }
}
```

--------------------------------

### Use HasTranslationStatus trait on EditRecord

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/README.md

Applies the HasTranslationStatus trait to a Filament EditRecord page to enable programmatic translation status checks. Must be used together with the Translatable concern.

```php
use JeffersonGoncalves\FilamentTranslatable\Concerns\HasTranslationStatus;

class EditPost extends EditRecord
{
    use EditRecord\Concerns\Translatable;
    use HasTranslationStatus;
}
```

--------------------------------

### Add Translatable trait to Filament resource

Source: https://github.com/jeffersongoncalves/filament-translatable/blob/3.x/resources/boost/skills/filament-translatable-development/SKILL.md

Add the Translatable concern to a Filament resource to enable translation features. This trait sets the content driver for search functionality.

```php
use JeffersonGoncalves\FilamentTranslatable\Resources\Concerns\Translatable;

class PostResource extends Resource
{
    use Translatable;
}
```
Tokens:
Raw