Localization

• Features
• Supported Components
  • Form Components
  • Table Columns
  • Infolist Entries
  • Layout Components
  • Filament Pages
  • Other Components
• Installation
• Configuration
• Commands
  • 1. filament:localize - Main Localization Command
  • 2. filament:translate-with-deepl - DeepL Translation Command
• Quick Start
• Translation File Structure
• How It Works
• Key Features
  • Smart Label Management
  • DeepL Integration
  • Page Localization Support
  • Smart Translation Detection
• Language Switching
• Before and After
  • Visual Comparison
    • Before Localization
    • After Localization
  • Code Comparison
• Safety Features
• Testing
• Contributing
• 💖 Support & Funding
• Support
• License

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.