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 2026-01-13 01:09 UTC

Requires

• php: >=7.3
• ext-json: *
• ext-pcre: *

MIT

• Ahmad Muhammad Rashad

• i18n
• translation
• gettext
• localization

README

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
• MO (Machine Object)
• PHP
• PO (Portable Object)
• XLIFF (XML Localization Interchange File Format)
• YAML

Table of Contents

• Requirements
• Installation
• Usage
• Handling Missing Translation Values
• Exceptions & Error Handling
• Contributing
• Credits
• License

Requirements

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

Installation

Install via Composer:

composer require alnaggar/php-translation-files

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

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

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

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

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

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 `<file>` node in the XLIFF 2.0 structure.
);

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

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

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

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

• Palestine banner and badge by Safouene1.

License

PhpTranslationFiles is open-sourced software licensed under the MIT license.