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.