Introduction

Laravel Locale Kit provides locale metadata for Laravel applications. It allows you to retrieve locale-specific information such as writing direction, number symbols, punctuation, calendar system, and other locale definitions.

The package also supports custom locale definitions and locale aliases.

Installation

Install the package via Composer:

composer require mohammad-zarifiyan/laravel-locale-kit:^2.0

Publishing Locale Definitions

To publish the predefined locale definition files into your application:

php artisan vendor:publish --provider="MohammadZarifiyan\LaravelLocaleKit\LocaleKitProvider" --tag="locale-kit-locales"

The files will be published to locales directory. You can edit the published files or add your own locale definitions.

Each locale definition file must be named using a locale identifier in the following format:

language_COUNTRY.json

Examples:

en_US.json
en_GB.json
fa_IR.json
fa_AF.json
ar_SA.json

You can edit the published files or add your own locale definition files.

Usage

alias()

Registers an alias for a locale identifier.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

LocaleKit::alias('fa', 'fa_IR');
LocaleKit::alias('en', 'en_US');
LocaleKit::alias('ar', 'ar_SA');

In this example, fa, en, and ar become aliases for the locale identifiers fa_IR, en_US, and ar_SA.

After registering an alias, any method that accepts a locale can use either the alias or the full locale identifier.

For example:

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

LocaleKit::get('direction', 'fa');

is equivalent to:

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

LocaleKit::get('direction', 'fa_IR');

aliases()

Returns all registered locale aliases.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

$aliases = LocaleKit::aliases();

Example result:

[
    'en' => 'en_US',
    'fa' => 'fa_IR',
    'ar' => 'ar_SA',
]

The returned array maps each alias to its corresponding locale identifier.

getIdentifier()

Returns the locale identifier for a locale or alias.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

LocaleKit::getIdentifier('fa'); // fa_IR
LocaleKit::getIdentifier('en'); // en_US
LocaleKit::getIdentifier('fa_AF'); // fa_AF

locales()

Returns all application locales available in Laravel's lang directory.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

$locales = LocaleKit::locales();

Example result:

[
    'en',
    'fa',
    'ar',
]

definedLocales()

Returns all locale definition files available to the package, including custom locale definitions.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

$locales = LocaleKit::definedLocales();

Example result:

[
    'en_US',
    'en_GB',
    'fa_IR',
    'ar_SA',
]

get()

Returns a value from a locale definition.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

LocaleKit::get('calendar_system', 'en_US');

Result:

'gregorian'

definitions()

Returns all loaded locale definitions.

use MohammadZarifiyan\LaravelLocaleKit\LocaleKit;

$definitions = LocaleKit::definitions();

Example result:

[
    'en_US' => [
        'direction' => 'ltr',
        'calendar_system' => 'gregorian',
        // ...
    ],
    'fa_IR' => [
        'direction' => 'rtl',
        'calendar_system' => 'jalali',
        // ...
    ],
]

The returned array is keyed by locale identifier, and each value contains the complete locale definition loaded by the package, including custom locale definitions.

Exporting Locale Definitions

You can export all loaded locale data into a single JSON file.

php artisan locale-kit:export resources/locales.json

The command accepts a single required argument: the destination file path.

Example output:

{
    "locales": [
        "en",
        "fa"
    ],
    "defined_locales": [
        "en_US",
        "fa_IR"
    ],
    "aliases": {
        "en": "en_US",
        "fa": "fa_IR"
    },
    "definitions": {
        "en_US": {
            "direction": "ltr"
        },
        "fa_IR": {
            "direction": "rtl"
        }
    }
}

The exported file contains:

| Key | Description | | ---- | ----------- | | locales | All application locales found in Laravel's lang directory. | | defined_locales | All available locale definitions, including custom definitions. | | aliases | All registered locale aliases. | | definitions | All loaded locale definitions. |

This export is useful for frontend applications, build pipelines, or any external service that needs access to the complete locale metadata without loading Laravel.