Introduction

js-locale-kit is a lightweight JavaScript implementation of locale metadata handling.
It is designed to be used alongside the mohammad-zarifiyan/laravel-locale-kit package, but it can also be used independently in any JavaScript/Node.js environment.

It provides access to locale definitions, aliases, and nested locale data structures.

Features

• Resolve locale identifiers from aliases
• Access nested locale definitions safely
• Work with Laravel-exported locale JSON files
• Framework-agnostic (works in Node.js and browsers with bundlers)
• Fully compatible with mohammad-zarifiyan/laravel-locale-kit export format

Installation

npm install js-locale-kit

or

yarn add js-locale-kit

Usage

Basic Setup

import LocaleKit from 'js-locale-kit';

const configuration = {
    locales: ['en', 'fa'],
    defined_locales: ['en_US', 'fa_IR'],
    aliases: {
        en: 'en_US',
        fa: 'fa_IR'
    },
    definitions: {
        en_US: {
            direction: 'ltr',
            calendar_system: 'gregorian'
        },
        fa_IR: {
            direction: 'rtl',
            calendar_system: 'jalali'
        }
    }
};

const kit = new LocaleKit(configuration, 'en');

API

constructor(configuration, defaultLocale)

Creates a new instance.

• configuration: Locale dataset (usually exported from Laravel)
• defaultLocale: fallback locale

getIdentifier(locale)

Resolves a locale or alias into a full locale identifier.

kit.getIdentifier('fa');   // fa_IR
kit.getIdentifier('fa_IR'); // fa_IR

aliases

Returns all registered aliases.

kit.aliases;

locales

Returns available application locales.

kit.locales;

definedLocales

Returns all defined locale identifiers.

kit.definedLocales;

get(key, locale)

Retrieves a value from locale definitions using dot notation.

kit.get('direction', 'fa');
kit.get('calendar_system', 'en_US');

Supports nested keys:

kit.get('numbers.decimal_separator', 'fa_IR');

Returns undefined if:

• locale is invalid
• definition does not exist
• key path is missing

Data Format Compatibility

LocaleKit JS is designed to consume data exported from mohammad-zarifiyan/laravel-locale-kit:

{
  "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"
    }
  }
}

Notes

• Locale format supports language_COUNTRY structure (e.g. en_US, fa_IR)
• Aliases are optional but recommended
• Nested key access is safe (no exceptions thrown on missing paths)