PHPackages                             alnaggar/php-translation-files - 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/php-translation-files

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

alnaggar/php-translation-files
==============================

A php package for simple, robust loaders and dumpers for common translation file formats. It aims to make conversion and manipulation of translation resources easy for CLI scripts, build steps, or server-side tooling.

1.0(5mo ago)041MITPHPPHP >=7.3

Since Jan 13Pushed 5mo agoCompare

[ Source](https://github.com/ahmed-rashad-alnaggar/php-translation-files)[ Packagist](https://packagist.org/packages/alnaggar/php-translation-files)[ RSS](/packages/alnaggar-php-translation-files/feed)WikiDiscussions main Synced today

READMEChangelog (1)DependenciesVersions (2)Used By (1)

PhpTranslationFiles
===================

[](#phptranslationfiles)

[![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/13dcc0656c854399d0e022e94e0fbe3dad5878f321cf9f5933fd5e1e11bbd188/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f616c6e61676761722f7068702d7472616e736c6174696f6e2d66696c6573)](https://packagist.org/packages/alnaggar/php-translation-files)[![Total Downloads](https://camo.githubusercontent.com/6295399d1e6ea2e6d7e5d7294b65bd3c34ab968683e08392b977fc548cddd678/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f616c6e61676761722f7068702d7472616e736c6174696f6e2d66696c6573)](https://packagist.org/packages/alnaggar/php-translation-files)[![License](https://camo.githubusercontent.com/d643eff4caf5ba80ac6f9643a7e57ea2658fd31178bb276b7ff68d9f216b8e53/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f616c6e61676761722f7068702d7472616e736c6174696f6e2d66696c6573)](https://packagist.org/packages/alnaggar/php-translation-files)

**PhpTranslationFiles** provides simple, robust loaders and dumpers for common translation file formats. It aims to make conversion and manipulation of translation resources easy for CLI scripts, build steps, or server-side tooling.

Supported formats:

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

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

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Handling Missing Translation Values](#handling-missing-translation-values)
- [Exceptions & Error Handling](#exceptions--error-handling)
- [Contributing](#contributing)
- [Credits](#credits)
- [License](#license)

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

[](#requirements)

- PHP 7.3+
- `ext-json` PHP extension
- `ext-pcre` PHP extension

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

[](#installation)

Install via Composer:

```
composer require alnaggar/php-translation-files
```

Usage
-----

[](#usage)

Each format has a Loader and a Dumper. Loaders implement `load(string $path): array` and return an array of translations. Dumpers implement `dump(array $translations, string $path, ...$options): static` which writes the file and returns the dumper instance.

### JSON

[](#json)

Load:

```
use Alnaggar\PhpTranslationFiles\Formats\Json\JsonFileLoader;

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

Dump:

```
use Alnaggar\PhpTranslationFiles\Formats\Json\JsonFileDumper;

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

$dumper = new JsonFileDumper();
$dumper->dump(
    translations: $translations,
    path: 'path/to/translations/file.json',
    flags: JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT // A bitmask that controls the behavior of the JSON encoding process.
);
```

### MO

[](#mo)

Load:

```
use Alnaggar\PhpTranslationFiles\Formats\Mo\MoFileLoader;

$loader = new MoFileLoader(
    contextDelimiter: '::',
    pluralDelimiter: '|'
);
$translations = $loader->load('path/to/translations/file.mo');
```

Dump:

```
use Alnaggar\PhpTranslationFiles\Formats\Mo\MoFileDumper;

$metadata = [
    'Language' => 'en',
    'Project-Id-Version' => '1.0'
];

$dumper = new MoFileDumper(
    contextDelimiter: '::',
    pluralDelimiter: '|'
);

$dumper->dump(
    translations: $translations,
    path: 'path/to/translations/file.mo',
    metadata: $metadata // An associative array to include additional information about the translation file, such as language, authorship, or pluralization rules.
);
```

### PHP

[](#php)

Load:

```
use Alnaggar\PhpTranslationFiles\Formats\Php\PhpFileLoader;

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

Dump:

```
use Alnaggar\PhpTranslationFiles\Formats\Php\PhpFileDumper;

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

### PO

[](#po)

Load:

```
use Alnaggar\PhpTranslationFiles\Formats\Po\PoFileLoader;

$loader = new PoFileLoader(
    contextDelimiter: '::',
    pluralDelimiter: '|'
);
$translations = $loader->load('path/to/translations/file.po');
```

Dump:

```
use Alnaggar\PhpTranslationFiles\Formats\Po\PoFileDumper;

$metadata = [
    'Language' => 'en',
    'Project-Id-Version' => '1.0'
];

$dumper = new PoFileDumper(
    contextDelimiter: '::',
    pluralDelimiter: '|'
);

$dumper->dump(
    translations: $translations,
    path: 'path/to/translations/file.po',
    metadata: $metadata // An associative array to include additional information about the translation file, such as language, authorship, or pluralization rules.
);
```

### XLIFF

[](#xliff)

Load:

```
use Alnaggar\PhpTranslationFiles\Formats\Xliff\XliffFileLoader;

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

Dump:

```
use Alnaggar\PhpTranslationFiles\Formats\Xliff\XliffFileDumper;

$dumper = new XliffFileDumper();
$dumper->dump(
    translations: $translations,
    path: 'path/to/translations/file.xliff',
    sourceLocale: 'en', // Specifies the source language of the translations.
    targetLocale: 'en', // Specifies the target language of the translations.
    legacy: false, // Determines whether to confrom to XLIFF 1.2 (`true`) or XLIFF 2.0 (`false`).
    fileId: 'en' // 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.
);
```

### YAML

[](#yaml)

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).

Load:

```
use Alnaggar\PhpTranslationFiles\Formats\Yaml\YamlFileLoader;

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

Dump:

```
use Alnaggar\PhpTranslationFiles\Formats\Yaml\YamlFileDumper;

$dumper = new YamlFileDumper();
$dumper->dump(
    translations: $translations,
    path: 'path/to/translations/file.yaml',
    dry: true // Determines whether to generate anchors and aliases for similar **mappings** in the YAML structure.
);
```

Handling Missing Translation Values
-----------------------------------

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

All loaders inherit a method to set a callback for handling missing translation values. If a value is `''` or `null`, the loader will use the translation key as a fallback, so missing translations are visibly flagged in the UI for correction.

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

- The missing translation `$key`
- The `$path` of the translations file holding the key

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

Example:

```
$loader->setMissingTranslationValueCallback(static function (string $key, string $path): string {
    error_log("Found an untranslated key: [{$key}] while loading the translations at [{$path}]");

    // Return a fallback value for missing keys.
    return strtoupper($key);
});

$translations = $loader->load('...');
```

Exceptions & Error Handling
-------------------------------

[](#exceptions--error-handling)

Loaders and dumpers throw specific exceptions to help you handle errors properly:

- `Alnaggar\PhpTranslationFiles\Exceptions\FileNotFoundException` — file not found (invalid path)
- `Alnaggar\PhpTranslationFiles\Exceptions\FileLoadException` — failed to open/read file
- `Alnaggar\PhpTranslationFiles\Exceptions\FileParsingException` — file content could not be parsed (invalid JSON/YAML/PO/etc.)
- `Alnaggar\PhpTranslationFiles\Exceptions\InvalidFileException` — file structure is invalid (e.g., non-UTF8 YAML, invalid MO header)
- `Alnaggar\PhpTranslationFiles\Exceptions\DirectoryNotFoundException` — target directory does not exist and cannot be created
- `Alnaggar\PhpTranslationFiles\Exceptions\FileDumpException` — failed to write output file

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)

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

###  Health Score

29

—

LowBetter than 57% of packages

Maintenance70

Regular maintenance activity

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity30

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

Unknown

Total

1

Last Release

171d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/131385452?v=4)[ahmed-rashad-alnaggar](/maintainers/ahmed-rashad-alnaggar)[@ahmed-rashad-alnaggar](https://github.com/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 (1 commits)")

---

Tags

localizationi18ntranslationgettext

### Embed Badge

![Health badge](/badges/alnaggar-php-translation-files/health.svg)

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

###  Alternatives

[gettext/gettext

PHP gettext manager

70232.6M118](/packages/gettext-gettext)[tio/laravel

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

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

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

29109.6k3](/packages/fisharebest-localization)[tractorcow/silverstripe-fluent

Simple localisation for Silverstripe

91437.9k29](/packages/tractorcow-silverstripe-fluent)[delight-im/i18n

Internationalization and localization for PHP

595.4k3](/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)