PHPackages                             alnaggar/mujam - 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/mujam

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

alnaggar/mujam
==============

A Laravel package for managing translations.

4.0(3mo ago)021MITPHPPHP >=7.3

Since Aug 13Pushed 3mo ago1 watchersCompare

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

READMEChangelog (9)Dependencies (6)Versions (10)Used By (0)

Mujam - A Translation Manager
=============================

[](#mujam---a-translation-manager)

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

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

[![Latest Stable Version](https://camo.githubusercontent.com/694a6d5eccc87cc82da9829dc5762495e53622218e254c6647e3db4c377c58cf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c6e61676761722f6d756a616d)](https://packagist.org/packages/alnaggar/mujam)[![Total Downloads](https://camo.githubusercontent.com/c0f271933985ac2e5e9613dee55131eaec939a9b8068eec31c564d4ef4b29a2d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616c6e61676761722f6d756a616d)](https://packagist.org/packages/alnaggar/mujam)[![License](https://camo.githubusercontent.com/844a86808ecfb2c7133450bb26114b7585b3c29f9158d34c8246a8822636841a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616c6e61676761722f6d756a616d)](https://packagist.org/packages/alnaggar/mujam)

**Mujam** is a Laravel translation management package that provides a flexible way to handle translations in your application. It supports various translation stores and allows for easy customization.

The name "**Mujam**" translates to "dictionary" or "lexicon" in Arabic, which reflects the purpose of the package as a translation management tool.

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

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Laravel Translation Functions](#laravel-translation-functions)
- [Stores](#stores)
- [Caching](#caching)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

Requirements
------------

[](#requirements)

- PHP 7.3+
- Laravel 8+

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

[](#installation)

Install the package using Composer:

```
composer require alnaggar/mujam
```

Then, publish the configuration file:

```
php artisan vendor:publish --tag="mujam-config"
```

Note

If you intend to use the [database store](#database-store), publish the default migrations or create your own and update `config/mujam.php` accordingly.

```
php artisan vendor:publish --tag="mujam-migrations"
```

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

[](#configuration)

The configuration file `config/mujam.php` contains the following keys:

- **default**: The default translation store.
- **stores**: The *enabled* translation stores, which include:

    - [database](#database-store)
    - [json](#json-store)
    - [mo](#mo-store)
    - [php](#php-store)
    - [po](#po-store)
    - [xliff](#xliff-store)
    - [yaml](#yaml-store)

    Refer to [creating custom store](#creating-custom-store) for guidance on supporting additional store types.

Flat and Structured Stores
--------------------------

[](#flat-and-structured-stores)

**Mujam** supports the two types of translation stores to suit different project needs:

1. **Flat Stores**: These stores use a simple key-value structure, ideal for straightforward translations. A common example is the [**JSON**](#json-store) store, where translations are stored in a flat format, making it easy to access and modify individual key-value pairs.
2. **Structured Stores**: These stores offer a more organized approach by supporting namespaces and groups, allowing for better organization and scalability. The [**PHP**](#php-store) store is a typical example, where translations are structured within files, grouped by namespace and language, providing a more modular and hierarchical way to manage translations.

Usage
-----

[](#usage)

To integrate Mujam into your application, you can use its translation features through the facade or by utilizing the `mujam()` helper function.

You can call functions directly on the facade to interact with the default store, or use the `store()` method to target a specific store.

**Below are examples of how to utilize the facade functions:**

### Retrieving Translation

[](#retrieving-translation)

```
$welcomeMessage = Mujam::store('php')->get(
    key: 'messages.welcome',
    locale: 'en',
    fallback: true
);
```

Retrieve the translation for the specified `key` and `locale`, or `null` if not found.

If `locale` is `null`, the current application locale is used.

The `fallback` parameter controls fallback behavior:

- If a locale is provided, fallback to it.
- If `true` or `null`, fallback to application's fallback locale.
- If `false`, no fallback will be applied, using only translations from the specified `locale`.

Both flat and structured stores use the same function signature. Simply provide the translation `key` and the `locale` to get the translation for.

### Retrieving Translations

[](#retrieving-translations)

**For Flat Store**:

```
$storeTranslations = Mujam::store('json')->getAll(
    locale: 'en',
    fallback: true
);
```

If `locale` is `null`, the current application locale is used.

The `fallback` parameter controls fallback behavior:

- If a locale is provided, fallback to it.
- If `true` or `null`, fallback to application's fallback locale.
- If `false`, no fallback will be applied, using only translations from the specified `locale`.

**For Structured Store**:

```
$storeTranslations = Mujam::store('php')->getAll(
    group: 'messages',
    namespace: '*',
    locale: 'en',
    fallback: true
);
```

The `namespace` can be set to `*` to indicate the default namespace.

The `locale` parameter works the same as for the flat store.

The `fallback` parameter works the same as for the flat store.

### Adding Translations

[](#adding-translations)

**For Flat Store**:

```
Mujam::store('json')->add(
    translations: ['Welcome to Mujam!' => 'Welcome to Mujam!'],
    locale: 'en'
);
```

The `translations` are provided as an associative array, where keys are the translation keys and values are the corresponding translation strings.

The `locale` parameter determines for which locale the translations should be added:

- If `null`, translations are added to the current application locale.
- If `*`, translations are added to all available locales.
- If a specific locale is provided, translations are added to that locale.
- Multiple locales can also be specified, separated by `|`.

**For Structured Store**:

```
Mujam::store('php')->add(
    translations: ['welcome' => 'Welcome to Mujam!'],
    group: 'messages',
    namespace: '*',
    locale: 'en'
);
```

The `translations` parameter works the same as for the flat store.

The `namespace` can be set to `*` to indicate the default namespace.

The `locale` parameter works the same as for the flat store.

### Updating Translations

[](#updating-translations)

**For Flat Store**:

```
Mujam::store('json')->update(
    translations: ['Welcome to Mujam!' => 'Welcome to the Translation Manager!'],
    locale: 'en'
);
```

The `translations` are provided as an associative array, where keys are the translation keys and values are the corresponding translation strings.

The `locale` parameter specifies the locale for which translations should be updated:

- If `null`, translations are updated for the current application locale.
- If `*`, translations are updated for all available locales.
- If a specific locale is provided, translations are updated for that locale.
- Multiple locales can also be provided, separated by `|`.

**For Structured Store**:

```
Mujam::store('php')->update(
    translations: ['welcome' => 'Welcome to the Translation Manager!'],
    group: 'messages',
    namespace: '*',
    locale: 'en'
);
```

The `translations` parameter works the same as for the flat store.

The `namespace` can be set to `*` to indicate the default namespace.

The `locale` parameter works the same as for the flat store.

### Removing Translations

[](#removing-translations)

**For Flat Store**:

```
Mujam::store('json')->remove(
    keys: ['Welcome to Mujam!'],
    locale: 'en'
);
```

The `keys` parameter is an array of keys where each key represents a specific translation that will be removed.

The `locale` parameter specifies the locale for which translations should be removed:

- If `null`, the translations are removed from the current application locale.
- If `*`, the translations are removed from all available locales.
- If a specific locale is provided, translations are removed from that locale.
- Multiple locales can also be provided, separated by `|`.

**For Structured Store**:

```
Mujam::store('php')->remove(
    items: ['welcome'],
    group: 'messages',
    namespace: '*',
    locale: 'en'
);
```

The `items` parameter is an array of keys where each key represents a specific translation that will be removed.

The `namespace` can be set to `*` to indicate the default namespace.

The `locale` parameter works the same as for the flat store.

### Flushing Store

[](#flushing-store)

**For Flat Store**:

```
Mujam::store('json')->flush(locale: '*');
```

The `locale` parameter specifies the locale for which translations should be removed:

- If `null`, all translations for the current application locale are removed.
- If `*`, all translations for all available locales are removed.
- If a specific locale is provided, all translations are removed for that locale.
- Multiple locales can also be provided, separated by `|`.

**For Structured Store**:

```
Mujam::store('php')->flush(
    group: '*',
    namespace: null,
    locale: '*'
);
```

The `group` can be set to `*` to indicate all groups.

The `namespace` parameter specifies the namespace for which translations should be removed:

- If `null`, all translations for all namespaces are removed.
- If `*`, all translations for the default namespace are removed.
- If a specific namespace is provided, all translations are removed for that namespace.
- Multiple namespaces can also be provided, separated by `|`.

The `locale` parameter specifies the locale for which translations should be removed:

- If `null`, the translations are removed from the current application locale.
- If `*`, the translations are removed from all available locales.
- If a specific locale is provided, translations are removed from that locale.
- Multiple locales can also be provided, separated by `|`.

### Checking Translation Existence

[](#checking-translation-existence)

```
if (Mujam::store('php')->has(
    key: 'messages.welcome',
    locale: 'en'
)) {
    // Translation exists
}
```

Check if a translation exists for the specified `key` and `locale`.

If `locale` is `null`, the current application locale is used.

Both flat and structured stores use the same function signature. Simply provide the translation `key` and the `locale` to check for the translation.

### Getting Store Structure

[](#getting-store-structure)

**For Flat Store**:

For retrieving an array of locales that have available translations:

```
$storeLocales = Mujam::store('json')->getLocales();
```

**For Structured Store**:

For retrieving store structure:

```
// Retrieves the store structure as an associative array with namespaces as the top-level keys, locales as the second-level keys, and groups as the third-level values.
$storeStructure = Mujam::store('php')->getStructure();
```

Laravel Translation Functions
-----------------------------

[](#laravel-translation-functions)

You can also use Laravel's `__` helper function or any other translation retrieval function, which will fetch translations from the provided and enabled stores.

```
// Fetches the translation from the enabled stores.
$welcomeMessage = __('messages.welcome');

// Package translations continue to work as expected.
$packageTranslation = __('packageNamespace::group.item');
```

Note

If multiple stores provide a translation for the same key, the last one defined will override the previous ones.

Stores
------

[](#stores)

### Database Store

[](#database-store)

- Driver: `database`
- Configuration:
    - `connection`: The database connection to use.
    - `table`: The table name to store translations in.
    - `columns`:
        - `namespace`: The column name for the translation namespace.
        - `group`: The column name for the translation group.
        - `item`: The column name for the translation item.
        - `locale`: The column name for the translation locale.
        - `value`: The column name for the translation value.
        - `created_at`: The column name for the translation created\_at timestamp.
        - `updated_at`: The column name for the translation updated\_at timestamp.

### JSON Store

[](#json-store)

- Driver: `json`
- Configuration:
    - `path`: A path or an array of paths from which JSON `translation` files are loaded and to which they are saved.
    - `flags`: A bitmask of flags to use when encoding JSON translations.

### MO Store

[](#mo-store)

- Driver: `mo`
- Configuration:
    - `path`: A path or an array of paths from which MO translation files are loaded and to which they are saved.
    - `context_delimiter`: The delimiter to use when splitting context strings.
    - `plural_delimiter`: The delimiter to use when splitting plural strings.
    - `metadata`: An array of metadata to include in the MO files.

### PHP Store

[](#php-store)

- Driver: `php`
- Configuration:
    - `path`: A path or an array of paths from which PHP translation files are loaded and to which they are saved.

### PO Store

[](#po-store)

- Driver: `po`
- Configuration:
    - `path`: A path or an array of paths from which PO translation files are loaded and to which they are saved.
    - `context_delimiter`: The delimiter to use when splitting context strings.
    - `plural_delimiter`: The delimiter to use when splitting plural strings.
    - `metadata`: An array of metadata to include in the PO files.

### XLIFF Store

[](#xliff-store)

- Driver: `xliff`
- Configuration:
    - `path`: A path or an array of paths from which XLIFF translation files are loaded and to which they are saved.
    - `source_locale`: The source locale attribute to use in XLIFF files. Assigning `null` will use application's fallback locale.
    - `legacy`: Whether to use the XLIFF 1.2 (`true`) or XLIFF 2.0 format (`false`).

### YAML Store

[](#yaml-store)

- Driver: `yaml`
- Configuration:
    - `path`: A path or an array of paths from which YAML translation files are loaded and to which they are saved.
    - `dry`: Determines whether to generate anchors and aliases for similar **mappings** in the YAML structure.

### Creating Custom Store

[](#creating-custom-store)

You can register a new driver within the `boot` method of one of your application's service providers. To accomplish this, you should use the `extend` method of the `Mujam` facade:

```
// Inside AppServiceProvider

public function boot()
{
    Mujam::extend(
        driver: 'customDriverName',
        resolver: function ($app, $config) {
            // return the custom store instance.
        }
    );
}
```

Caching
-------

[](#caching)

**All** translation stores in **Mujam** support caching to improve performance and reduce repeated file or database reads. Caching behavior is fully configurable through the `cache` key in each store’s configuration.

Caching can be customized per store to control how long translations remain valid, where they are stored, and how cache keys are organized.

**Example PHP cache configuration:**

```
'stores' => [
    'php' => [
        'driver' => 'php',
        'path' => lang_path(),
        'cache' => [
            'enabled' => true,
            'store' => null, // Use application's default cache store
            'prefix' => 'mujam.php',
            'lifetime' => 9999999999, // Forever
        ],
    ],
]
```

Caching can be disabled by setting `enabled` to `false`, or by setting the entire `cache` key to `false`.

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)

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

###  Health Score

36

—

LowBetter than 81% of packages

Maintenance84

Actively maintained with recent releases

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity40

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 ~65 days

Recently: every ~24 days

Total

9

Last Release

112d ago

Major Versions

1.0 → 2.02025-03-23

2.7.2 → 3.02025-10-14

3.0 → 4.02026-01-17

PHP version history (2 changes)1.0PHP ^7.3|^8.0

4.0PHP >=7.3

### 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 (23 commits)")

---

Tags

laravellocalizationtranslation

### Embed Badge

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

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

###  Alternatives

[kkomelin/laravel-translatable-string-exporter

Translatable String Exporter for Laravel

3291.4M10](/packages/kkomelin-laravel-translatable-string-exporter)[barryvdh/laravel-translation-manager

Manage Laravel Translations

1.7k3.6M17](/packages/barryvdh-laravel-translation-manager)[tio/laravel

Add this package to localize your Laravel application (PHP, JSON or GetText).

170318.5k](/packages/tio-laravel)[opgginc/codezero-laravel-localized-routes

A convenient way to set up, manage and use localized routes in a Laravel app.

2770.1k1](/packages/opgginc-codezero-laravel-localized-routes)[longman/laravel-multilang

Package to integrate multi language (multi locale) functionality in Laravel 5.x

5514.4k1](/packages/longman-laravel-multilang)

PHPackages © 2026

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