smmahfujurrahman/localization

A Laravel package providing Artisan commands to extract, auto-translate, wrap, and sort Blade translation strings with Google Translate support.

v1.0.0 2026-04-25 15:14 UTC

Requires

• php: ^8.1|^8.2|^8.3|^8.4
• illuminate/console: ^10.0|^11.0|^12.0|^13.0
• illuminate/support: ^10.0|^11.0|^12.0|^13.0
• stichoza/google-translate-php: ^5.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0

MIT

• SM Mahfujur Rahman

• i18n
• translation
• laravel
• localization
• extract
• blade
• google-translate
• auto-translate

README

A Laravel package that provides three Artisan commands to fully automate your translation workflow:

Command	What it does
localization:extract	Scans all Blade files for __() / @lang() calls and extracts keys to a JSON file. Optionally auto-translates via Google Translate.
localization:wrap	Scans all Blade files and wraps un-translated static text with __() automatically.
localization:sort	Sorts any translation JSON file alphabetically by key.

Requirements

• PHP 8.1+
• Laravel 10, 11, or 12
• Internet connection (for localization:extract with a target language)

Installation

composer require smmahfujurrahman/localization

Laravel auto-discovers the service provider. No manual registration needed.

Publish Configuration (Recommended)

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

This creates config/localization.php where you can customise all paths and settings:

return [
    // Directory scanned by localization:wrap (default: resources/views)
    'views_path' => resource_path('views'),

    // Directory used by localization:extract and localization:sort
    // null = auto-detect (/lang on Laravel 9+, /resources/lang on older)
    'lang_path' => null,

    // Microsecond delay between Google Translate API calls (default: 100ms)
    'translate_delay' => 100000,

    // Backup directory prefix for localization:wrap (null = auto-generate)
    'backup_path' => null,

    // Filename for the empty key template (no language argument)
    'template_filename' => 'template_empty.json',

    // Source language for Google Translate (null = auto-detect)
    'source_language' => 'en',
];

Usage

localization:extract — Extract & Auto-Translate

Scan all Blade views and extract every __('...') and @lang('...') key into a JSON file.

# Create an empty template (lang/template_empty.json)
php artisan localization:extract

# Auto-translate to French (creates lang/fr.json)
php artisan localization:extract fr

# Auto-translate to Arabic
php artisan localization:extract ar

# Auto-translate to Bengali
php artisan localization:extract bn

# Auto-translate to German
php artisan localization:extract de

Smart re-run: If a target language file already exists, keys that already have a translation are preserved — only new/missing keys are translated. You can re-run safely without overwriting manual edits.

localization:wrap — Wrap Un-Translated Text

Automatically find static English text in your Blade files and wrap it with __().

# Always preview first!
php artisan localization:wrap --dry-run

# Apply changes to all Blade files
php artisan localization:wrap

A timestamped backup of your views directory is created automatically before any files are modified.

Handles 21 patterns including:

• Simple tag text: <p>Dashboard</p> → <p>{{ __('Dashboard') }}</p>
• Dynamic variables: <span>{{ $type }} Management</span> → <span>{{ __(':type Management', ['type' => $type]) }}</span>
• HTML attributes: placeholder, title, alt, label
• Fallback values: {{ $var ?? 'Default' }} → {{ $var ?? __('Default') }}
• Button text, long paragraphs, emoji text, and more

localization:sort — Sort a Translation File

Sort any JSON translation file alphabetically by key for easier management.

php artisan localization:sort ar.json
php artisan localization:sort fr.json
php artisan localization:sort en.json

Typical Workflow

# Step 1: Wrap any un-translated text in your Blade files (dry run first)
php artisan localization:wrap --dry-run
php artisan localization:wrap

# Step 2: Extract all translation keys
php artisan localization:extract

# Step 3: Auto-translate to your target languages
php artisan localization:extract ar
php artisan localization:extract fr
php artisan localization:extract bn

# Step 4: Sort the files for easier management
php artisan localization:sort ar.json
php artisan localization:sort fr.json

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributor

Support

For support and questions:

• 📧 Email: [e-mail]