Filament Localization Package

The first and only automatic Filament localization package with intelligent resource scanning, structured translation files, and comprehensive testing. This package eliminates the repetitive task of manually adding translation keys to every field, column, action, and component in your Filament application.

This is the original and only package that provides automatic localization with translation features for Filament.

Requirements: PHP ^8.3 | ^8.4 | ^8.5 · Laravel ^12.0 · Filament ^5.0 (Livewire ^4.0, Tailwind ^4.0)

Supported: PHP ^8.3–^8.5, Laravel ^12.0, Filament ^5.0, Livewire ^4.0 · Deprecated: PHP <8.3, Filament v4 (use v1.x), Livewire v3.

🆕 Latest Updates: v2.x — Filament 5 & Livewire 4 support; PHP 8.5; enhanced DeepL integration, page localization, and skip terms.

Features

• 🚀 Automatic Scanning: Scans all Filament resources, pages, and relation managers
• 🏗️ Smart Localization: Removes hardcoded labels and creates translation keys
• 🤖 DeepL Integration: Intelligent translation with smart detection of untranslated content
• 📊 Structured Organization: Creates organized translation files
• 🔄 Git Integration: Automatic commits for easy reverting
• ⚡ Zero Configuration: Works out of the box
• 🎯 Selective Processing: Process specific panels or all at once
• 🔒 Safe Operation: Backups and dry-run mode
• 🧠 Smart Detection: Automatically detects untranslated content
• 🚫 Skip Terms: Intelligently skips acronyms and technical terms

Supported Components

Form Components

• TextInput, Textarea, Select, DatePicker, DateTimePicker, TimePicker
• Checkbox, Toggle, Radio, FileUpload
• RichEditor, MarkdownEditor, ColorPicker
• KeyValue, Repeater, Builder, TagsInput
• CheckboxList, Hidden, ViewField

Table Columns

• TextColumn, IconColumn, ImageColumn, ColorColumn
• CheckboxColumn, ToggleColumn, SelectColumn, TextInputColumn

Infolist Entries

• TextEntry, IconEntry, ImageEntry, ColorEntry
• KeyValueEntry, RepeatableEntry

Layout Components

• Section, Fieldset, Grid, Tabs, Wizard, Step, Group

Filament Pages

• Dashboard pages with static properties
• Custom pages with hardcoded strings
• Page methods (getTitle, getHeading, getNavigationLabel)

Other Components

• Actions, Filters, Notifications, Relation Managers

Installation

Install the package via Composer (automatically installs all dependencies):

composer require mominalzaraa/filament-localization

Publish the configuration file:

php artisan vendor:publish --tag="filament-localization-config"

Configuration

The configuration file config/filament-localization.php provides customization options:

return [
    'default_locale' => 'en',
    'locales' => ['en', 'el', 'fr'],
    'structure' => 'panel-based', // flat, nested, or panel-based
    'backup' => true,
    'git' => [
        'enabled' => true,
        'commit_message' => 'chore: add Filament localization support',
    ],
    'excluded_panels' => [],
    'excluded_resources' => [],
    'translation_key_prefix' => 'filament',
    
    // Skip Terms - Terms that should remain the same across languages
    'skip_identical_terms' => [
        'API', 'URL', 'HTTP', 'HTTPS', 'PDF', 'CSV', 'JSON', 'XML',
        'Laravel', 'Filament', 'Vue', 'React', 'Angular', 'Google', 'Microsoft',
        'GitHub', 'Docker', 'AWS', 'Azure', 'PayPal', 'Stripe', 'WordPress',
        'Bootstrap', 'Tailwind', 'jQuery', 'TypeScript', 'Webpack', 'Vite',
        'JWT', 'OAuth', 'REST', 'GraphQL', 'SEO', 'UX', 'UI', 'SaaS', 'PaaS',
        'IoT', 'AI', 'ML', 'DevOps', 'CI/CD', 'Agile', 'Scrum', 'TDD', 'BDD',
        'GDPR', 'ISO', 'IEEE', 'W3C', 'OWASP', 'NIST', 'ITIL', 'PMP',
    ],
    
    // DeepL Translation Configuration
    'deepl' => [
        'api_key' => env('DEEPL_API_KEY'),
        'base_url' => env('DEEPL_BASE_URL', 'https://api-free.deepl.com/v2'),
        'timeout' => 60,
        'batch_size' => 50,
        'preserve_formatting' => true,
    ],
];

Commands

The package provides two commands for localization and translation:

1. filament:localize - Main Localization Command

Scans and localizes Filament resources with structured translation files.

# Basic usage
php artisan filament:localize

# Specific panels and locales
php artisan filament:localize --panel=admin --locale=en --locale=el

# Preview changes
php artisan filament:localize --dry-run

# Force update existing labels
php artisan filament:localize --force

# Skip git commit
php artisan filament:localize --no-git

Options:

• --panel=* - Specific panel(s) to localize
• --locale=* - Specific locale(s) to generate
• --force - Force localization even if labels exist
• --no-git - Skip git commit
• --dry-run - Preview changes without applying them

2. filament:translate-with-deepl - DeepL Translation Command

Intelligently translates Filament resources using the DeepL API with smart detection of untranslated content.

Prerequisites:

1. Get a DeepL API key from DeepL API
2. Add to your .env file: DEEPL_API_KEY=your_deepl_api_key_here

# Smart translation - detects untranslated content automatically
php artisan filament:translate-with-deepl --source-lang=en --target-lang=el --panel=admin

# Force mode - overwrites all existing translations
php artisan filament:translate-with-deepl --source-lang=en --target-lang=fr --panel=admin --force

# Multiple panels with preview
php artisan filament:translate-with-deepl --source-lang=en --target-lang=de --panel=admin --panel=blog --dry-run

Features:

• Smart Detection: Automatically detects untranslated content
• Skip Terms: Intelligently skips acronyms and technical terms
• Force Mode: Overwrites existing translations when using --force
• Mixed Content: Processes files with both translated and untranslated content

Options:

• --source-lang=SOURCE-LANG - Source language code (default: "en")
• --target-lang=TARGET-LANG - Target language code (required)
• --panel=PANEL - Specific panel(s) to translate
• --force - Force translation and overwrite all existing translations
• --dry-run - Preview changes without applying them

Supported Languages: 40+ languages including English, Greek, French, German, Italian, Portuguese, Russian, Japanese, Chinese, Arabic, and more.

Quick Start

1. Generate translation files:

   php artisan filament:localize --panel=admin
   

2. Translate with DeepL (optional):

   php artisan filament:translate-with-deepl --source-lang=en --target-lang=el --panel=admin
   

3. Install language switcher:

   composer require craft-forge/filament-language-switcher
   

4. Configure in your panel provider:

   FilamentLanguageSwitcherPlugin::make()
       ->locales([
           ['code' => 'en', 'name' => 'English', 'flag' => 'gb'],
           ['code' => 'el', 'name' => 'Greek', 'flag' => 'gr'],
       ])
   

Translation File Structure

The package creates organized translation files based on your configuration:

Panel-Based Structure (Recommended):

lang/
├── en/filament/admin/user_resource.php
├── en/filament/blog/post_resource.php
└── el/filament/admin/user_resource.php

Other Structures: Nested or flat structures available via configuration.

How It Works

1. Scans all Filament resources, pages, and relation managers
2. Identifies localizable components (fields, columns, actions, static properties, methods)
3. Removes hardcoded labels and replaces with translation keys
4. Creates organized translation files with default labels
5. Updates resource and page files to use dynamic translation keys
6. Intelligently translates using DeepL API with smart detection:
   • Missing keys (keys that don't exist in target language)
   • Untranslated content (identical to source language)
   • Skips acronyms and technical terms that should remain the same
7. Creates git commit for easy reverting

Key Features

Smart Label Management

Automatically removes hardcoded labels and replaces them with translation keys:

// Before
protected static ?string $modelLabel = 'Articles';

// After  
protected static ?string $modelLabel = null;

public static function getModelLabel(): string
{
    return __('filament/admin/user_resource.model_label');
}

DeepL Integration

• Smart Detection: Automatically detects untranslated content
• Skip Terms: Intelligently skips acronyms and technical terms
• Force Mode: Overwrites existing translations when using --force
• Mixed Content: Processes files with both translated and untranslated content
• High accuracy translations with 40+ supported languages
• Context-aware processing with formatting preservation
• Batch processing with usage monitoring
• Graceful error handling and fallbacks

Page Localization Support

Now supports Filament pages with static properties and methods:

// Before
class Dashboard extends BaseDashboard
{
    protected static ?string $title = 'Blog Dashboard';
    protected static ?string $navigationLabel = 'Dashboard';
}

// After
class Dashboard extends BaseDashboard
{
    protected static ?string $title = null;
    protected static ?string $navigationLabel = null;

    public function getTitle(): string
    {
        return __('filament/admin/dashboard.title');
    }

    public static function getNavigationLabel(): string
    {
        return __('filament/admin/dashboard.navigation_label');
    }
}

Smart Translation Detection

The DeepL translation command intelligently detects what needs to be translated:

Normal Mode (Default):

• Translates missing keys (keys that don't exist in target language)
• Translates keys with identical content to source (indicating untranslated content)
• Skips terms configured in skip_identical_terms (e.g., "SMS", "API", "URL")
• Preserves existing properly translated content

Force Mode (--force):

• Overwrites ALL existing translations with new ones from source language
• Useful for complete retranslation or when source language has been updated

Example Scenarios:

// Source (English)
return [
    'title' => 'Blog Dashboard',
    'navigation_label' => 'Send Email',
    'description' => 'Manage your blog posts and comments',
];

// Target (Greek) - Before Translation
return [
    'title' => 'Blog Dashboard',           // ← Will be translated (identical to source)
    'navigation_label' => 'Send Email',    // ← Will be translated (not in skip terms)
    'description' => 'Διαχείριση των δημοσιεύσεων σας', // ← Will be preserved (properly translated)
];

// Target (Greek) - After Translation
return [
    'title' => 'Πίνακας Ελέγχου Ιστολογίου',            // ← Translated
    'navigation_label' => 'Αποστολή Email',  // ← Translated
    'description' => 'Διαχείριση των δημοσιεύσεων σας', // ← Preserved
];

Language Switching

This package generates translation files. To enable language switching in your Filament panels, install a language switcher plugin:

Recommended: craft-forge/filament-language-switcher

composer require craft-forge/filament-language-switcher

Configure in your panel provider:

use CraftForge\FilamentLanguageSwitcher\FilamentLanguageSwitcherPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentLanguageSwitcherPlugin::make()
                ->locales([
                    ['code' => 'en', 'name' => 'English', 'flag' => 'gb'],
                    ['code' => 'el', 'name' => 'Greek', 'flag' => 'gr'],
                ]),
        ]);
}

Other options: filament/spatie-laravel-translatable-plugin, awcodes/filament-language-switcher

Before and After

Visual Comparison

Before Localization

The Filament admin interface displays in English with hardcoded labels:

Users list page showing English labels

User edit form with English field labels

File structure showing only English translation files

After Localization

The same interface now supports multiple languages with proper translation keys:

Users list page with localized Greek labels

User edit form with localized Greek field labels

File structure showing organized translation files for multiple locales

Code Comparison

Before Localization:

TextInput::make('name')->required(),
TextColumn::make('email')->searchable(),
Action::make('delete')->requiresConfirmation(),

After Localization:

TextInput::make('name')
    ->label(__('filament/admin/user_resource.name'))
    ->required(),

TextColumn::make('email')
    ->label(__('filament/admin/user_resource.email'))
    ->searchable(),

Action::make('delete')
    ->label(__('filament/admin/user_resource.delete'))
    ->requiresConfirmation(),

Translation Files Created:

// lang/en/filament/admin/user_resource.php
return ['name' => 'Name', 'email' => 'Email', 'delete' => 'Delete'];

// lang/el/filament/admin/user_resource.php  
return ['name' => 'Όνομα', 'email' => 'Email', 'delete' => 'Διαγραφή'];

Safety Features

• Backups: Creates timestamped backups before modifying files
• Git Integration: Automatic commit for easy reverting (git reset --soft HEAD~1)
• Dry Run: Preview changes before applying
• Error Handling: Comprehensive error reporting

Testing

composer test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

💖 Support & Funding

If this package has helped you, please consider supporting its development:

• ⭐ Star the repository on GitHub
• 🐛 Report bugs and suggest features
• 💰 Sponsor the project on GitHub Sponsors
• 📧 Email: support@mominpert.com
• 🌐 Website: mominpert.com
• 💬 GitHub Issues: Report an issue

Support

• 📧 Email: support@mominpert.com
• 🌐 Website: mominpert.com
• 💬 GitHub Issues: Report an issue

License

The MIT License (MIT). Please see License File for more information.