PHPackages                             alnaggar/turjuman - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. alnaggar/turjuman

ActiveLibrary[Localization & i18n](/categories/localization)

alnaggar/turjuman
=================

Laravel package for route localization.

v1.2.0(2y ago)112MITPHP

Since Dec 3Pushed 2y ago1 watchersCompare

[ Source](https://github.com/ahmed-rashad-alnaggar/turjuman)[ Packagist](https://packagist.org/packages/alnaggar/turjuman)[ RSS](/packages/alnaggar-turjuman/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (4)Dependencies (1)Versions (5)Used By (0)

Turjuman - Laravel Route Localization Package
=============================================

[](#turjuman---laravel-route-localization-package)

[![I Stand With Palestine Badge](./images/PalestineBadge.svg)](./images/PalestineBadge.svg)

[![I Stand With Palestine Banner](./images/PalestineBanner.svg)](./images/PalestineBanner.svg)

Turjuman is a Laravel route localization package designed to simplify the process of generating localized routes effortlessly. The name "turjuman" is derived from the Arabic word **تُرجُمان**, meaning the person who translates or localizes. This term holds historical significance as it was the name of one of [alsahaba](https://en.wikipedia.org/wiki/Companions_of_the_Prophet) (companions) of the [Prophet Muhammad](https://en.wikipedia.org/wiki/Muhammad) may Allah bless him and grant him peace, Abdullah bin Abbas. He earned the title of "turjuman" (the interpreter) of the holy [Qur’an](https://en.wikipedia.org/wiki/Quran) due to his renowned skills in interpreting the holy Qur’an, despite being one of the youngest companions.

Table of Contents
-----------------

[](#table-of-contents)

- [Installation](#installation)
- [Configuration](#configuration)
- [Middlewares](#middlewares)
- [Features](#features)
- [Usage](#usage)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

Installation
------------

[](#installation)

Turjuman is compatible with Laravel 10 and above.

Install the package using Composer:

```
composer require alnaggar/turjuman
```

Next, publish the configuration file:

```
php artisan vendor:publish --provider="Alnaggar\Turjuman\TurjumanServiceProvider"
```

Then, register these middlewares in your `app/http/kernel.php` before the `\Illuminate\Routing\Middleware\SubstituteBindings` middleware

```
 'web' => [
    // ...

    \Alnaggar\Turjuman\Middleware\SetLocale::class,
    \Alnaggar\Turjuman\Middleware\LocalizeRoutes::class,
    \Illuminate\Routing\Middleware\SubstituteBindings::class,
],
```

Configuration
-------------

[](#configuration)

The Configuration file (`config/turjuman.php`) provides flexibility in defining supported locales, default locale, display options, hiding the default locale, route aliases, and locale identifier.

### Supported Locales

[](#supported-locales)

The `supported_locales` key in allows you to specify the locales you want to support. With a vast array of +800 locales available, you can uncomment or add new ones based on your project needs. Each locale can be customized with additional properties such as currency, country, etc., making them accessible through the corresponding `Locale` instance.

Note

Ensure compliance with ISO 15897 for locale codes and language directories, as [recommended](https://laravel.com/docs/10.x/localization#using-short-keys) by Laravel for better experience.

### Default Locale

[](#default-locale)

The `default_locale` key sets the code for the default locale. Turjuman will fallback to this locale when no locale is detected.

### Display Locale in URL

[](#display-locale-in-url)

The `display_location` key controls how the locale is displayed in the URL. It can be a positive integer, indicating the segment to display, a string specifying the query name for display, or null to hide the locale from the URL while setting it internally.

### Hide Default Locale

[](#hide-default-locale)

The `hide_default` key, when set to true, determines whether to display the default locale in the URL if it's displayable.

### Route Aliases

[](#route-aliases)

The `route_aliases` key allows you to translate specific URLs in different locales. For instance, you can provide custom slugs and/or domains for URLs by adding them under the corresponding locale keys.

### Locale Identifier

[](#locale-identifier)

The `locale_identifier` key allows you to set the locale token name used in url parameters, session, cookies and form input to identify the current locale.

Middlewares
-----------

[](#middlewares)

### `SetLocale.php` Middleware

[](#setlocalephp-middleware)

This middleware is responsible for setting the current locale based on various sources in a predefined order, such as request input, URL, session, cookies, browser languages, and user preferences to determine the current locale.

In addition to this, you have the option to publish a middleware named `TurjumanSetLocale` using the artisan command:

```
php artisan turjuman:middleware
```

By doing so, you can effortlessly override the `fetchUserLocale(): ?string` function within this middleware. This function allows you to retrieve the user's preferred locale from the database or any other source if it is not determined in the predefined sources. After publishing, replace the existing `\Alnaggar\Turjuman\Middleware\SetLocale::class` middleware in your `app/http/kernel.php` with `\App\Http\Middleware\TurjumanSetLocale::class` middleware. This provides a convenient way to customize how the user's preferred locale is fetched, allowing you to adapt it according to your specific requirements.

### `LocalizeRoutes.php` Middleware

[](#localizeroutesphp-middleware)

This middleware is responsible for handling localization of routes based on the current locale settings. It checks if the request is a GET request and if current route is localized. It ensures that the URL matches the localized URL, and if not, it redirects to the correct URL.

Features
--------

[](#features)

### Route Localization

[](#route-localization)

Easily create localized routes for different languages or regions by utilizing the group function.

```
//  routes/web.php
use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function(){
    Route::get('/', function(){
        return view('welcome');
    });

    Route::get('/show/{id}', ['\App\Http\Controllers\UserController::class', 'index']);

    Route::post('/edit/{id}', ['\App\Http\Controllers\UserController::class', 'update']);

    // ...
});
```

### Locale Aliases

[](#locale-aliases)

You can define an alias for the locale to appear in the url in the configuration of the locale instead of the locale code.

```
// confing/turjuman.php

'supported_locales' => [
    'ar' => ['name' => 'Arabic', 'native' => 'العربية', 'script' => 'Arab', 'alias' => 'العربية'],
    'en' => ['name' => 'English', 'native' => 'English', 'script' => 'Latn', 'alias' => 'English'],
    'fr' => ['name' => 'French', 'native' => 'français', 'script' => 'Latn'], // no alias.

    // ...
],
```

### Localized URL Generation

[](#localized-url-generation)

Generate localized URLs based on configured locales and group attributes.

```
use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'route_aliases' => [
        'fr' => [
            '/products' => '/produits'
        ]
    ]
]);
```

```
use Alnaggar\Turjuman\Turjuman;

$url = Turjuman::getLocalizedUrl('/products', 'fr');
// Returns the URL for the 'fr' locale: '/fr/produits'
```

### Group Attributes

[](#group-attributes)

Define custom attributes for route groups to control display type, default locale, and more.

```
use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'supported_locales' => [...], // Specify supported locales
    'default_locale' => 'en', // Set the default locale
    // Add more group attributes as needed
]);
```

### Extensible and Macroable

[](#extensible-and-macroable)

Extend the functionality of Turjuman by adding macros and mixins.

```
use Alnaggar\Turjuman\Turjuman;

// Adding Macros
Turjuman::macro('customMethod', function () {
    // Your custom logic here
});

/// Adding Mixins
Turjuman::mixin(new MyCustomMixin());
```

`Alnaggar\Turjuman\Locale` and `Alnaggar\Turjuman\GroupAttributes` are utilizing `Alnaggar\Turjuman\Traits\Extensible` triat, making them macroable and may have additional properties, this properties may be accessed by array-access, property-access, or get-method-access.

```
// config/turjuman.php

'supported_locales' => [
    'ar_DZ' => ['name' => 'Arabic (Algeria)', 'native' => 'العربية (الجزائر)', 'script' => 'Arab', 'currency' => 'DZD'],
    'ar_EG' => ['name' => 'Arabic (Egypt)', 'native' => 'العربية (مصر)', 'script' => 'Arab', 'currency' => 'EGP']
]

// ... other configurations
```

```
// routes/web.php

use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'continent' => 'Africa',
    'common_language' => 'Arabic'
]);
```

```
// YourClass.php

use Alnaggar\Turjuman\Turjuman;

public function getDetails()
{
    $currency = Turjuman::getCurrentLocale()['currency'];
    $continent = Turjuman::getCurrentAttributes()->continent;
    $commonLanguage = Turjuman::getCurrentAttributes()->getCommonLanguage();

    // ...
}
```

Note

The custom properties must be named using ***snake\_case***.

### Redirecting Only When Needed

[](#redirecting-only-when-needed)

The redirection mechanism is selectively applied, exclusively triggering when a GET request is encountered. For other types of requests, the locale is internally set without initiating any redirection.

### Standard Route Caching

[](#standard-route-caching)

Feel free to employ any of Laravel's standard route caching commands as usual.

Usage
-----

[](#usage)

### Route Grouping

[](#route-grouping)

#### `group(\Closure $routes, array $attributes = []): \Alnaggar\Turjuman\Group`

[](#groupclosure-routes-array-attributes---alnaggarturjumangroup)

The `group` function is a powerful feature allowing you to group routes for localization. It takes a closure containing the routes to localize and optional attributes. You can add custom attributes overriding the conifg ones, making it ideal for multi-tenancy applications with different locales.

```
use Alnaggar\Turjuman\Facades\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here
}, [
    'default_locale' => 'en',
    'display_location' => 'lang',
    // More custom attributes...
]);
```

#### `ignore(\Illuminate\Routing\Route|\Closure $routes): void`

[](#ignoreilluminateroutingrouteclosure-routes-void)

Use the `ignore` function within the `group` closure to exclude specific routes from localization. It takes a closure or a single route to ignore.

```
use Alnaggar\Turjuman\Turjuman;

Turjuman::group(function () {
    // Define your localized routes here

    Turjuman::ignore(function() {
        // Define your non-localized routes here
    });
});
```

### Configuration Management

[](#configuration-management)

#### `addConfigLocales(array $locales): \Alnaggar\Turjuman\Localizer`

[](#addconfiglocalesarray-locales-alnaggarturjumanlocalizer)

Add additional locales to the supported locales in the configuration.

Example:

```
// App/Providers/AppServiceProvider.php

use \Alnaggar\Turjuman\Locale;
use \Alnaggar\Turjuman\Turjuman;

$locales = [
    new Locale(['code' => 'fr', 'name' => 'French', 'native' => 'français', 'script' => 'Latn']),
    new Locale(['code' => 'es', 'name' => 'Spanish', 'native' => 'español', 'script' => 'Latn']),
];

Turjuman::addConfigLocales($locales);
```

#### `setConfigLocales(array $locales): \Alnaggar\Turjuman\Localizer`

[](#setconfiglocalesarray-locales-alnaggarturjumanlocalizer)

Set the supported locales in the configuration.

Example:

```
// App/Providers/AppServiceProvider.php

use \Alnaggar\Turjuman\Locale;
use \Alnaggar\Turjuman\Turjuman;

$locales = [
    // Define your locales.
];

Turjuman::setConfigLocales($locales);
```

#### `setConfigDefaultLocale(string $locale): \Alnaggar\Turjuman\Localizer`

[](#setconfigdefaultlocalestring-locale-alnaggarturjumanlocalizer)

Set the default locale in the configuration.

Example:

```
// App/Providers/AppServiceProvider.php

use \Alnaggar\Turjuman\Turjuman;

Turjuman::setConfigDefaultLocale('fr');
```

#### `getConfigAttributes(): \Alnaggar\Turjuman\GroupAttributes`

[](#getconfigattributes-alnaggarturjumangroupattributes)

Retrieve the configuration attributes.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$configAttributes = Turjuman::getConfigAttributes();
```

### Group Information

[](#group-information)

#### `getCurrentGroup(): ?\Alnaggar\Turjuman\Group`

[](#getcurrentgroup-alnaggarturjumangroup)

Retrieve the `Alnaggar\Turjuman\Group` instance responsible for localizing the current route. Returns `null` if not found.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$currentGroup = Turjuman::getCurrentGroup();
```

#### `getCurrentAttributes(): \Alnaggar\Turjuman\GroupAttributes`

[](#getcurrentattributes-alnaggarturjumangroupattributes)

Retrieve the current group attributes.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$currentAttributes = Turjuman::getCurrentAttributes();
```

### Locale Management

[](#locale-management)

#### `setCurrentLocale(string $locale): \Alnaggar\Turjuman\Locale`

[](#setcurrentlocalestring-locale-alnaggarturjumanlocale)

Set the current locale.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

Turjuman::setCurrentLocale('es');
```

#### `getLocale(string $locale): ?\Alnaggar\Turjuman\Locale`

[](#getlocalestring-locale-alnaggarturjumanlocale)

Retrieve an `Alnaggar\Turjuman\Locale` instance based on its code. Returns `null` if the locale is not supported.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$arabicLocale = Turjuman::getLocale('ar');
```

#### `getSupportedLocales(): array`

[](#getsupportedlocales-array)

Retrieve the current group's supported locales.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$supportedLocales = Turjuman::getSupportedLocales();
```

#### `getDefaultLocale(): \Alnaggar\Turjuman\Locale`

[](#getdefaultlocale-alnaggarturjumanlocale)

Retrieve the current group's default locale instance.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$defaultLocale = Turjuman::getDefaultLocale();
```

#### `getCurrentLocale(): ?\Alnaggar\Turjuman\Locale`

[](#getcurrentlocale-alnaggarturjumanlocale)

Retrieve the current locale instace. Returns `null` if the current route is not localized.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$currentLocale = Turjuman::getCurrentLocale();
```

### URL Localization

[](#url-localization)

#### `getLocalizedUrl(string $url, ?string $locale = null): ?string`

[](#getlocalizedurlstring-url-string-locale--null-string)

Get the localized URL for the provided URL and locale. Returns `null` if the provided URL is external or not localized.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$spanishUrl = Turjuman::getLocalizedUrl('/about', 'es');
```

#### `getNonLocalizedUrl(string $url): ?string`

[](#getnonlocalizedurlstring-url-string)

Get the non-localized URL for the provided URL. Returns `null` if the provided URL is external.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$originalUrl = Turjuman::getNonLocalizedUrl('/acerca-de');
```

### Localization Validation

[](#localization-validation)

#### `isLocalizedUrl(string $url, string $method = 'GET'): bool`

[](#islocalizedurlstring-url-string-method--get-bool)

Check if the given URL is localized in any of the registered groups.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$isLocalizedUrl = Turjuman::isLocalizedUrl('/contact');
```

#### `isLocalizedRoute(\Illuminate\Routing\Route|string|null $route = null): bool`

[](#islocalizedrouteilluminateroutingroutestringnull-route--null-bool)

Check if the provided route is localized within any of the registered groups. The check is done against the current route if `null` is passed.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$isLocalizedUrl = Turjuman::isLocalizedRoute('main.contact');
```

### Locale Validation

[](#locale-validation)

#### `isSupportedLocale(string $locale): bool`

[](#issupportedlocalestring-locale-bool)

Check if the provided locale is supported within the current group.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$isSupported = Turjuman::isSupportedLocale('es');
```

#### `isCurrentLocale(string $locale): bool`

[](#iscurrentlocalestring-locale-bool)

Check if the provided locale is the current locale.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$isCurrent = Turjuman::isCurrentLocale('fr');
```

#### `isDefaultLocale(string $locale): bool`

[](#isdefaultlocalestring-locale-bool)

Check if the provided locale is the default locale.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$isDefault = Turjuman::isDefaultLocale('en');
```

### Miscellaneous

[](#miscellaneous)

#### `getLocalesByProperty(string $property, mixed $default = null): string`

[](#getlocalesbypropertystring-property-mixed-default--null-string)

Retrieve an associative array of locale codes and their corresponding property values based on the current group's supported locales.

The `$default` optional parameter specifies the value to be returned if the property does not exist for a certain locale instance. If a closure is passed, the locale instance will be provided as a parameter. This function is useful for obtaining specific information or settings for each supported locale within the currently defined group. It provides flexibility by allowing a default value or behavior to be specified in case the requested property is not available for a particular locale.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$localesCurrencies = Turjuman::getLocalesByProperty('currency', 'USD');
```

#### `getLocalizedPagePath(string $path, ?string $locale = null): string`

[](#getlocalizedpagepathstring-path-string-locale--null-string)

Get the localized page path for the provided path and locale. It works for Laravel views and [Inertia](https://inertiajs.com/) pages.

Example:

```
use \Alnaggar\Turjuman\Turjuman;

$localizedPath = Turjuman::getLocalizedPagePath('contact', 'fr');
```

Note

Before using functions that rely on the current group or current attributes, it is essential to include an `if` statement to check whether the current route is localized.

### Helper Function

[](#helper-function)

The `turjuman` helper function can be used to localize URLs:

```
// Get the localized URL for a given path and locale
$url = turjuman('/about', 'ar');
```

Contributing
------------

[](#contributing)

If you find any issues or have suggestions for improvements, feel free to open an issue or submit a pull request on the GitHub repository.

Credits
-------

[](#credits)

- Palestine banner and badge by [Safouene1](https://github.com/Safouene1/support-palestine-banner).

License
-------

[](#license)

Turjuman is open-sourced software licensed under the [MIT license](LICENSE).

###  Health Score

22

—

LowBetter than 22% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~5 days

Total

4

Last Release

875d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/deb82fef56c6147e5256320e88516da1909e25764a692938928eb1929de809db?d=identicon)[ahmed-rashad-alnaggar](/maintainers/ahmed-rashad-alnaggar)

---

Top Contributors

[![ahmed-rashad-alnaggar](https://avatars.githubusercontent.com/u/131385452?v=4)](https://github.com/ahmed-rashad-alnaggar "ahmed-rashad-alnaggar (5 commits)")

---

Tags

laravellocalizationtranslationroute

### Embed Badge

![Health badge](/badges/alnaggar-turjuman/health.svg)

```
[![Health](https://phpackages.com/badges/alnaggar-turjuman/health.svg)](https://phpackages.com/packages/alnaggar-turjuman)
```

###  Alternatives

[waavi/translation

A Translation package for Laravel 5 with database and cache support

367437.9k6](/packages/waavi-translation)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)