README

A professional Laravel package to generate multilingual UTF-8 slugs with smart, configurable skipping of transliteration for specific locales (like Arabic, Farsi, Urdu, etc.), while keeping Laravel’s original Str::slug() behavior intact.

🚀 Features

Generate clean, SEO-friendly slugs for any language
Skip transliteration automatically for configurable locales (e.g., ar, fa, ur)
Fully compatible with Laravel’s Str helper
Supports Laravel 9, 10, 11, 12
Zero config (but highly configurable if needed)
Auto-discovered (no need to manually register service provider)
Publishable config file for easy customization
Supports custom dictionary replacements and force skip

📦 Installation

composer require developvi/laravel-slug-i18n

⚙️ Configuration

You can publish the config file with:

php artisan vendor:publish --tag=slug-i18n-config

.env Options

SLUG_I18N_ENABLED: Enable or disable the package (default: true)
SLUG_I18N_SKIP_LOCALES: Comma-separated list of locales to skip transliteration for (e.g., ar,fa,ur)

Example:

SLUG_I18N_ENABLED=true
SLUG_I18N_SKIP_LOCALES=ar,fa,ur

config/slug-i18n.php

You can also edit the config file directly for advanced control:

return [
    'enabled' => env('SLUG_I18N_ENABLED', true),
    'skip_locales' => [
        ...array_filter(
            explode(',', (string) env('SLUG_I18N_SKIP_LOCALES', ''))
        ),
    ],
];

🧑‍💻 Usage

Basic Usage

Use the new macro Str::slugI18n for full control:

use Illuminate\Support\Str;

// Will skip transliteration for Arabic if configured
$slug = Str::slugI18n('مثال على نص عربي', '-', 'ar'); // Output: مثال-على-نص-عربي

// Will transliterate for English
$slug = Str::slugI18n('Example English Text', '-', 'en'); // Output: example-english-text

Macro Signature

Str::slugI18n(
    string $title,
    string $separator = '-',
    string $language = 'en',
    array $dictionary = ['@' => 'at'],
    bool $forceSkip = false
): string

$title: The string to slugify
$separator: Word separator (default: '-')
$language: Language/locale code (e.g., 'ar', 'en', ...)
$dictionary: Custom replacements (e.g., ['@' => 'at'])
$forceSkip: If true, always skip transliteration regardless of config

Advanced Usage

// Custom dictionary and force skip
$slug = Str::slugI18n('Laravel@10 ❤️', '-', 'en', ['@' => 'at', '❤️' => 'love'], true); // laravel-at-10-love

// Force skip transliteration for any language
$slug = Str::slugI18n('مثال على نص عربي', '-', 'en', [], true); // مثال-على-نص-عربي

🧪 Testing

To run the package tests:

composer install
./vendor/bin/phpunit

📝 License

MIT

👤 Author

Eslam El Sherif
dev@eslamelsherif.com

💡 Example in Laravel Route

use Illuminate\Support\Str;

Route::get('/slug', function () {
    $slug = Str::slugI18n('مرحبا بك', forceSkip: true);
    return $slug; // Output: مرحبا-بك
});

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

developvi / laravel-slug-i18n

Maintainers

Details