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

Abandoned → [alnaggar/php-translation-files](/?search=alnaggar%2Fphp-translation-files)ArchivedLibrary[Localization & i18n](/categories/localization)

alnaggar/muhawil
================

A php package for loading and dumping translations.

2.0(1y ago)026MITPHPPHP >=7.3

Since Jul 21Pushed 3mo ago1 watchersCompare

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

READMEChangelog (4)DependenciesVersions (5)Used By (0)

Muhawil - PHP Package For Loading And Dumping Translations
==========================================================

[](#muhawil---php-package-for-loading-and-dumping-translations)

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

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

[![Deprecated](https://camo.githubusercontent.com/fe8320988d2a6ac3bfe751ca59747d22f8504bde277c4974f4f0d16db9e086a7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d646570726563617465642d726564)](https://camo.githubusercontent.com/fe8320988d2a6ac3bfe751ca59747d22f8504bde277c4974f4f0d16db9e086a7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7374617475732d646570726563617465642d726564)

Warning

This package is deprecated and no longer maintained. Please use **[`alnaggar/php-translation-files`](https://github.com/ahmed-rashad-alnaggar/php-translation-files)** instead.

Muhawil is a PHP package designed to simplify the process of loading and dumping translations. The name 'Muhawil' is derived from the Arabic word "**مُحَوِّل**", meaning transformer or adapter, as it facilitates reading and writing translations in several formats.

The package natively supports 6 file types:

- [JSON](#json)
- [MO (Machine Object)](#mo)
- [PHP](#php)
- [PO (Portable Object)](#po)
- [XLIFF (XML Localization Interchange File Format)](#xliff)
- [YAML](#yaml)

Additionally, you can create your own [custom loaders and dumpers](#custom-loaders-and-dumpers).

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

[](#requirements)

- PHP >= 7.3
- `ext-json` PHP extension
- `ext-pcre` PHP extension

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

[](#installation)

Install the package using Composer:

```
composer require alnaggar/muhawil
```

Loading Translations
--------------------

[](#loading-translations)

All files loaders extend the `Alnaggar\Muhawil\Loaders\FileLoader` abstract class, which provides the `load (string $path)` method to load the transaltions from the specified file.

```
# Example of loading translations from a PHP file.

use Alnaggar\Muhawil\Loaders\PhpFileLoader;

$loader = new PhpFileLoader;

$translations = $loader->load('path/to/translations/file.php');
```

### Handling Missing Translation Values

[](#handling-missing-translation-values)

The `FileLoader` class uses the `Alnaggar\Muhawil\Traits\HasMissingTranslationValueHandler` trait. By default, if a translation value is missing (empty or `null`), the translation **key** itself is returned. This makes missing translations are visibly flagged in the UI for correction.

To override this behavior, pass a callback to `setMissingTranslationValueCallback()` which receives:

- The translation `$key`.
- `$path` (only for `FileLoader` classes).

The callback function is responsible for determining and returning the appropriate value.

```
# Example of logging missing translations for later review.

use Alnaggar\Muhawil\Loaders\PhpFileLoader;

$loader = new PhpFileLoader;

$callback = function (string $key, string $path) {
  $message = "Found an untranslated key: {$key} while loading the translations at {$path}";
  error_log($message);

  // Return the key as the translation value so it can be visibly flagged for correction.
  return $key;
};

$loader->setMissingValueCallback($callback);

$translations = $loader->load('path/to/translations/file.php');
```

Dumping Translations
--------------------

[](#dumping-translations)

All file dumpers extend the `Alnaggar\Muhawil\Dumpers\FileDumper` abstract class, and each has its own `dump()` method signature as described in each section below.

JSON
----

[](#json)

Load JSON translations using `Alnaggar\Muhawil\Loaders\JsonFileLoader` class.

Dump JSON translations using `Alnaggar\Muhawil\Dumpers\JsonFileDumper` class, using its `dump(array $translations, string $path, int $flags = JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT): static` method.

- `$flags`: A bitmask that controls the behavior of the JSON encoding process.

```
// Example of dumping translations into a JSON file.

use Alnaggar\Muhawil\Dumpers\JsonFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new JsonFileDumper;

$dumper->dump($translations, 'path/to/translations/file.json', JSON_PRETTY_PRINT | JSON_INVALID_UTF8_IGNORE);
```

MO
--

[](#mo)

Load MO translations using `Alnaggar\Muhawil\Loaders\MoFileLoader` class.

Dump MO translations using `Alnaggar\Muhawil\Dumpers\MoFileDumper` class, using its `dump(array $translations, string $path, array $metadata = []): static` method.

- `$metadata`: An associative array to include additional information about the translation file, such as language, authorship, or pluralization rules.

The dumper uses the `Alnaggar\Muhawil\Traits\HasPluralForms` trait, to automatically generates the `Plural-Forms` metadata if the `Language` metadata is provided and `Plural-Forms` is not explicitly set.

Both The MO loader and dumper constructors accept two optional parameters:

- `?string $contextDelimiter = '::'`: Delimiter for message context in translation keys.
- `?string $pluralDelimiter = '|'`: Delimiter for pluralization in translation keys and values.

```
// Example of dumping translations into an MO file.

use Alnaggar\Muhawil\Dumpers\MoFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$metadata  = [
    'Language' => 'ar',
];

$dumper = new MoFileDumper;

$dumper->dump($translations, 'path/to/translations/file.mo', $metadata);
```

PHP
---

[](#php)

Load PHP translations using `Alnaggar\Muhawil\Loaders\PhpFileLoader` class.

Dump PHP translations using `Alnaggar\Muhawil\Dumpers\PhpFileDumper` class, using its `dump(array $translations, string $path): static` method.

```
// Example of dumping translations into a PHP file.

use Alnaggar\Muhawil\Dumpers\PhpFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new PhpFileDumper;

$dumper->dump($translations, 'path/to/translations/file.php');
```

PO
--

[](#po)

Load PO translations using `Alnaggar\Muhawil\Loaders\PoFileLoader` class.

Dump PO translations using `Alnaggar\Muhawil\Dumpers\PoFileDumper` class, using its `dump(array $translations, string $path, array $metadata = []): static` method.

- `$metadata`: An associative array to include additional information about the translation file, such as language, authorship, or pluralization rules.

The dumper uses the `Alnaggar\Muhawil\Traits\HasPluralForms` trait, to automatically generates the `Plural-Forms` metadata if the `Language` metadata is provided and `Plural-Forms` is not explicitly set.

Both The PO loader and dumper constructors accept two optional parameters:

- `?string $contextDelimiter = '::'`: Delimiter for message context in translation keys.
- `?string $pluralDelimiter = '|'`: Delimiter for pluralization in translation keys and values.

```
// Example of dumping translations into a PO file.

use Alnaggar\Muhawil\Dumpers\PoFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$metadata  = [
    'Language' => 'ar',
];

$dumper = new PoFileDumper;

$dumper->dump($translations, 'path/to/translations/file.po', $metadata);
```

XLIFF
-----

[](#xliff)

Load XLIFF translations using `Alnaggar\Muhawil\Loaders\XliffFileLoader` class.

Dump XLIFF translations using `Alnaggar\Muhawil\Dumpers\XliffFileDumper` class, using its `dump(array $translations, string $path, string $sourceLocale = 'en', string $targetLocale = 'en', bool $legacy = false, string $fileId = 'f1'): static` method.

- `$sourceLocale`: Specifies the source language of the translations.
- `$targetLocale`: Specifies the target language of the translations.
- `$legacy`: Determines whether to confrom to XLIFF 1.2 (`true`) or XLIFF 2.0 (`false`).
- `$fileId`: When `$legacy` is set to `false` (indicating XLIFF 2.0), this parameter is used to specify the `id` attribute for the `` node in the XLIFF 2.0 structure.

```
// Example of dumping translations into an XLIFF file.

use Alnaggar\Muhawil\Dumpers\XliffFileDumper;

$translations = [
    'welcome' => 'Welcome to our website!',
    'farewell' => 'Wishing you success on your new journey. Farewell!'
];

$dumper = new XliffFileDumper;

$dumper->dump($translations, 'path/to/translations/file.', 'en', 'en', false);
```

YAML
----

[](#yaml)

Load YAML translations using `Alnaggar\Muhawil\Loaders\YamlFileLoader` class.

Dump YAML translations using `Alnaggar\Muhawil\Dumpers\YamlFileDumper` class, using its `dump(array $translations, string $path, bool $dry = true): static` method.

- `$dry`: Determines whether to generate anchors and aliases for similar **mappings** in the YAML structure.

```
// Example of dumping translations into a YAML file.

use Alnaggar\Muhawil\Dumpers\YamlFileDumper;

$translations = [
    'welcome_message' => 'Welcome to our application!',
    'greeting' => 'Hello, world!',
    'farewell' => 'Goodbye, see you soon!',
    'errors' => [
        'not_found' => 'The requested resource was not found.',
        'internal_error' => 'An internal server error occurred. Please try again later.'
    ],
    'common_actions' => [
        'save' => 'Save',
        'cancel' => 'Cancel',
        'delete' => 'Delete'
    ],
    'user' => [
        'profile' => 'Profile',
        'settings' => 'Settings',
        'logout' => 'Logout',
        'actions' => [
            'create' => 'Create',
            'save' => 'Save',
            'cancel' => 'Cancel',
            'delete' => 'Delete'
        ]
    ]
];

$dumper = new YamlFileDumper;

$dumper->dump($translations, 'path/to/translations/file.yaml', true);
```

Both the YAML loader and dumper support only simple YAML structures, including mappings, nested mappings, and scalar values. Keys and scalar values may be double-quoted, single-quoted, or unquoted (as long as they do not contain special YAML characters).

Custom Loaders and Dumpers
--------------------------

[](#custom-loaders-and-dumpers)

You can implement your own loaders and dumpers for any type of storage, like a database or any other storage, by implementing the `Alnaggar\Muhawil\Interfaces\Loader` and `Alnaggar\Muhawil\Interfaces\Dumper` interfaces and their respective `load` and `dump` methods.

For example, to create a custom loader for a database, you would create a class that implements the `Loader` interface and define the `load` method to fetch translations from the database. Similarly, for a custom dumper, implement the `Dumper` interface and define the `dump` method to save translations back to the database.

This flexibility allows you to tailor Muhawil to your specific needs beyond the provided file-based loaders and dumpers.

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)

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

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance63

Regular maintenance activity

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

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

Total

4

Last Release

427d ago

Major Versions

1.1.0 → 2.02025-03-11

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

2.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 (18 commits)")

---

Tags

localizationi18ntranslationgettext

### Embed Badge

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

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

###  Alternatives

[gettext/gettext

PHP gettext manager

70530.2M102](/packages/gettext-gettext)[tio/laravel

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

170318.5k](/packages/tio-laravel)[fisharebest/localization

A lightweight localization database and translation tools, with data from the CLDR, IANA, ISO, etc.

3191.1k2](/packages/fisharebest-localization)[tractorcow/silverstripe-fluent

Simple localisation for Silverstripe

92421.6k26](/packages/tractorcow-silverstripe-fluent)[delight-im/i18n

Internationalization and localization for PHP

625.2k3](/packages/delight-im-i18n)[inpsyde/multilingual-press

Simply THE multisite-based free open source plugin for your multilingual websites.

2414.0k1](/packages/inpsyde-multilingual-press)

PHPackages © 2026

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