PHPackages omega-mvc/gettext - 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. omega-mvc/gettext ActiveLibrary[Localization & i18n](/categories/localization) omega-mvc/gettext ================= GNU gettext-based localization and translation support for the Omega ecosystem, providing message translation management and internationalization services. 1.0.0(1mo ago)072GPL-3.0-or-laterPHPPHP ^8.4CI passing Since Jul 12Pushed 6d agoCompare [ Source](https://github.com/omega-mvc/gettext)[ Packagist](https://packagist.org/packages/omega-mvc/gettext)[ Docs](https://github.com/php-gettext/Gettext)[ RSS](/packages/omega-mvc-gettext/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (8)Versions (2)Used By (2) [ ![Omega Logo](https://github.com/omega-mvc/omega-assets/raw/main/images/logo-omega.png) ](https://omega-mvc.github.io) [Documentation](https://omega-mvc.github.io) | [Changelog](https://github.com/omega-mvc/gettext/blob/main/CHANGELOG.md) | [Contributing](https://github.com/omega-mvc/gettext/blob/main/CONTRIBUTING.md) | [Code of Conduct](https://github.com/omega-mvc/gettext/blob/main/CODE_OF_CONDUCT.md) | [License](https://github.com/omega-mvc/gettext/blob/main/LICENSE) [![CI](https://github.com/omega-mvc/gettext/actions/workflows/ci.yml/badge.svg)](https://github.com/omega-mvc/gettext/actions/workflows/ci.yml) Gettext ======= [](#gettext) Gettext is a PHP 8.4+ library for working with internationalization (i18n) and localization (l10n). It provides tools to **import, export, edit, and merge translations** across multiple formats, such as PO, MO, PHP arrays, JSON, and JavaScript files. The library is designed to be flexible: you can scan source code to extract translatable strings, load existing translations from files, manipulate them in PHP, and finally generate the compiled output in the format required by your application or framework. Whether you are building a multilingual website, a PHP application, or a project that integrates templates and scripts, this package aims to provide a consistent API for all gettext-related operations. Table of Contents ----------------- [](#table-of-contents) - [Installation](#installation) - [Running Test](#running-test) - [Classes and Functions](#classes-and-functions) - [Usage Example](#quick-start) - [Translation](#translation) - [Translations](#translations) - [Translator](#translator) - [GettextTranslator](#gettexttranslator) - [Translator Functions](#translator-functions) - [Loaders](#loaders) - [ArrayLoader](#arrayloader) - [JsonLoader](#jsonloader) - [MoLoader](#moloader) - [PoLoader](#poloader) - [StrictPoLoader](#strictpoloader) - [Generators](#generators) - [ArrayGenerator](#arraygenerator) - [JsonGenerator](#jsongenerator) - [MoGenerator](#mogenerator) - [PoGenerator](#pogenerator) - [Scanners](#scanners) - [JsScanner](#jsscanner) - [PhpScanner](#phpscanner) - [Merging Translations](#merging-translations) Installation ------------ [](#installation) ``` composer require omega-mvc/gettext ``` Running Test ------------ [](#running-test) ``` vendor/bin/phpunit ``` Classes and functions --------------------- [](#classes-and-functions) This package contains the following classes: - `Gettext\Translation` - A translation definition - `Gettext\Translations` - A collection of translations (under the same domain) - `Gettext\Translator` - - `Gettext\Scanner\*` - Scan files to extract translations (php, js, twig templates, ...) - `Gettext\Loader\*` - Load translations from different formats (po, mo, json, ...) - `Gettext\Generator\*` - Export translations to various formats (po, mo, json, ...) Quick Start ----------- [](#quick-start) ``` use Gettext\Loader\PoLoader; use Gettext\Generator\MoGenerator; //import from a .po file: $loader = new PoLoader(); $translations = $loader->loadFile('locales/gl.po'); //edit some translations: $translation = $translations->find(null, 'apple'); if ($translation) { $translation->translate('Mazรก'); } //export to a .mo file: $generator = new MoGenerator(); $generator->generateFile($translations, 'Locale/gl/LC_MESSAGES/messages.mo'); ``` ### Translation [](#translation) The `Gettext\Translation` class stores all information about a translation: the original text, the translated text, source references, comments, etc. ``` use Gettext\Translation; $translation = Translation::create('comments', 'One comment', '%s comments'); $translation->translate('Un comentario'); $translation->translatePlural('%s comentarios'); $translation->getReferences()->add('templates/comments/comment.php', 34); $translation->getComments()->add('To display the amount of comments in a post'); echo $translation->getContext(); // comments echo $translation->getOriginal(); // One comment echo $translation->getTranslation(); // Un comentario // etc... ``` ### Translations [](#translations) The `Gettext\Translations` class stores a collection of translations: ``` use Gettext\Translations; $translations = Translations::create('my-domain'); //You can add new translations: $translation = Translation::create('comments', 'One comment', '%s comments'); $translations->add($translation); //Find a specific translation $translation = $translations->find('comments', 'One comment'); //Edit headers, domain, etc $translations->getHeaders()->set('Last-Translator', 'Oscar Otero'); $translations->setDomain('my-blog'); ``` ### Translator [](#translator) ``` use Gettext\Translator; //Create a new instance of the translator $t = new Translator(); //Load the translations from php files (generated by Gettext\Extractors\PhpArray) $t->loadTranslations( 'locales/gl/domain1.php', 'locales/gl/domain2.php', 'locales/gl/domain3.php', ); //Now you can use it in your templates echo $t->gettext('apple'); ``` ### GettextTranslator [](#gettexttranslator) The class `Gettext\GettextTranslator` uses the gettext extension. It's useful because combines the performance of using real gettext functions but with the same API as `Translator` class, so you can switch to one or other translator without change code of your app. ``` use Gettext\GettextTranslator; //Create a new instance $t = new GettextTranslator(); //It detects the environment variables to set the locale, but you can change it: $t->setLanguage('gl'); //Load the domains: $t->loadDomain('messages', 'project/Locale'); //this means you have the file "project/Locale/gl/LC_MESSAGES/messages.mo" //Now you can use it in your templates echo $t->gettext('apple'); ``` ### Translator functions [](#translator-functions) To ease the use of translations in your php templates, you can use the provided functions: ``` use Gettext\TranslatorFunctions; //Register the translator to use the global functions TranslatorFunctions::register($t); echo __('apple'); // it's the same as $t->gettext('apple'); ``` You can scan the php files containing these functions and extract the values with the PhpCode extractor: ``` ``` Loaders ------- [](#loaders) This package includes the following loaders: - `ArrayLoader` - `JsonLoader` - `MoLoader` - `PoLoader` - `StrictPoLoader` - The loaders allow to get gettext values from multiple formats. For example, to load a .po file: ### ArrayLoader [](#arrayloader) ### JsonLoader [](#jsonloader) ### MoLoader [](#moloader) ### PoLoader [](#poloader) ``` use Gettext\Loader\PoLoader; $loader = new PoLoader(); //From a file $translations = $loader->loadFile('locales/en.po'); //From a string $string = file_get_contents('locales2/en.po'); $translations = $loader->loadString($string); ``` ### StrictPoLoader [](#strictpoloader) `StrictPoLoader` is a parser more aligned to the GNU gettext tooling with the same expectations and failures (see the tests for more details). - It will fail with an exception when there's anything wrong with the syntax, and display the reason together with the line/byte where it happened. - It might also emit useful warnings, e.g. when there are more/less plural translations than needed, missing translation header, dangling comments not associated with any translation, etc. - Due to its strictness and speed (about 50% slower than the `PoLoader`), it might be interesting to be used as a kind of `.po` linter in a build system. - It also implements the previous translation comment (e.g. `#| msgid "previous"`) and extra escapes (16-bit unicode `\u`, 32-bit unicode `\U`, hexadecimal `\xFF` and octal `\77`). The usage is basically the same as the `PoLoader`: ``` use Gettext\Loader\StrictPoLoader; $loader = new StrictPoLoader(); //From a file $translations = $loader->loadFile('locales/en.po'); //From a string $string = file_get_contents('locales2/en.po'); $translations = $loader->loadString($string); //Display error messages using "at line X column Y" instead of "at byte X" $loader->displayErrorLine = true; //Throw an exception when a warning happens $loader->throwOnWarning = true; //Retrieve the warnings $loader->getWarnings(); ``` Generators ---------- [](#generators) The generators export a `Gettext\Translations` instance to any format (po, mo, etc.). This package includes the following generators: - `ArrayGenerator` - `JsonGenerator` - `MoGenerator` - `PoGenerator` ### ArrayGenerator [](#arraygenerator) ArrayGenerator generates PHP array files from gettext translations with optional pretty-printing and strict types. ``` use Gettext\Generator\ArrayGenerator; use Gettext\Loader\PoLoader; // Load translations from a .po file $loader = new PoLoader(); $translations = $loader->loadFile('locales/en.po'); // Generate PHP array file with pretty print and strict types $generator = new ArrayGenerator([ 'pretty' => true, 'strictTypes' => true ]); $phpCode = $generator->generateString($translations); file_put_contents('locale/en/messages.php', $phpCode); ``` ### JsonGenerator [](#jsongenerator) JsonGenerator generates JSON files from gettext translations with configurable JSON options. ``` use Gettext\Loader\PoLoader; use Gettext\Loader\JsonLoader; use Gettext\Generator\JsonGenerator; use Gettext\Translations; //Load a .po file and export to .json $translations = (new PoLoader())->loadFile('locales/translations.po'); (new JsonGenerator())->generateFile($translations, 'locales/translations.json'); //You can load the json file with JsonLoader $loadedTranslations = (new JsonLoader())->loadFile('locales/translations.json'); ``` ### MoGenerator [](#mogenerator) MoGenerator generates binary .mo files from gettext translations, optionally including headers ``` use Gettext\Loader\PoLoader; use Gettext\Generator\MoGenerator; //Load a PO file $poLoader = new PoLoader(); $translations = $poLoader->loadFile('locales/en.po'); //Save to MO file $moGenerator = new MoGenerator(); $moGenerator->generateFile($translations, 'locales/en.mo'); //Or return as a string $content = $moGenerator->generateString($translations); file_put_contents('locales/en.mo', $content); ``` ### PoGenerator [](#pogenerator) PoGenerator generates human-readable .po files from gettext translations. ``` use Gettext\Loader\PoLoader; use Gettext\Generator\PoGenerator; // Load translations from a PO file $loader = new PoLoader(); $translations = $loader->loadFile('locales/en.po'); // Generate a .po string $generator = new PoGenerator(); $poContent = $generator->generateString($translations); // Save to a file file_put_contents('locales/generated.po', $poContent); ``` Scanners -------- [](#scanners) Scanners allow to search and extract new gettext entries from different sources like php files, twig templates, blade templates, etc. Unlike loaders, scanners allows to extract gettext entries with different domains at the same time: This package includes the following scanners: - `JsScanner` - `PhpScanner` ### JsScanner [](#jsscanner) ``` use Gettext\Scanner\JsScanner; use Gettext\Generator\PoGenerator; use Gettext\Translations; //Create a new scanner, adding a translation for each domain we want to get: $jsScanner = new JsScanner( Translations::create('domain1'), Translations::create('domain2'), Translations::create('domain3') ); //Scan files foreach (glob('*.js') as $file) { $jsScanner->scanFile($file); } //Save the translations in .po files $generator = new PoGenerator(); foreach ($jsScanner->getTranslations() as $translations) { $domain = $translations->getDomain(); $generator->generateFile($translations, "locales/{$domain}.po"); } ``` ### PhpScanner [](#phpscanner) ``` use Gettext\Scanner\PhpScanner; use Gettext\Generator\PoGenerator; use Gettext\Translations; //Create a new scanner, adding a translation for each domain we want to get: $phpScanner = new PhpScanner( Translations::create('domain1'), Translations::create('domain2'), Translations::create('domain3') ); //Set a default domain, so any translations with no domain specified, will be added to that domain $phpScanner->setDefaultDomain('domain1'); //Extract all comments starting with 'i18n:' and 'Translators:' $phpScanner->extractCommentsStartingWith('i18n:', 'Translators:'); //Scan files foreach (glob('*.php') as $file) { $phpScanner->scanFile($file); } //Save the translations in .po files $generator = new PoGenerator(); foreach ($phpScanner->getTranslations() as $domain => $translations) { $generator->generateFile($translations, "locales/{$domain}.po"); } ``` Merging translations -------------------- [](#merging-translations) You will want to update or merge translations. The function `mergeWith` create a new `Translations` instance with other translations merged: ``` $translations3 = $translations1->mergeWith($translations2); ``` But sometimes this is not enough, and this is why we have merging options, allowing to configure how two translations will be merged. These options are defined as constants in the `Gettext\Merge` class, and are the following: ConstantDescription`Merge::TRANSLATIONS_OURS`Use only the translations present in `$translations1``Merge::TRANSLATIONS_THEIRS`Use only the translations present in `$translations2``Merge::TRANSLATIONS_OVERRIDE`Override the translation and plural translations with the value of `$translation2``Merge::HEADERS_OURS`Use only the headers of `$translations1``Merge::HEADERS_REMOVE`Use only the headers of `$translations2``Merge::HEADERS_OVERRIDE`Overrides the headers with the values of `$translations2``Merge::COMMENTS_OURS`Use only the comments of `$translation1``Merge::COMMENTS_THEIRS`Use only the comments of `$translation2``Merge::EXTRACTED_COMMENTS_OURS`Use only the extracted comments of `$translation1``Merge::EXTRACTED_COMMENTS_THEIRS`Use only the extracted comments of `$translation2``Merge::FLAGS_OURS`Use only the flags of `$translation1``Merge::FLAGS_THEIRS`Use only the flags of `$translation2``Merge::REFERENCES_OURS`Use only the references of `$translation1``Merge::REFERENCES_THEIRS`Use only the references of `$translation2`Use the second argument to configure the merging strategy: ``` $strategy = Merge::TRANSLATIONS_OURS | Merge::HEADERS_OURS; $translations3 = $translations1->mergeWith($translations2, $strategy); ``` There are some typical scenarios, one of the most common: - Scan php templates searching for entries to translate - Complete these entries with the translations stored in a .po file - You may want to add new entries to the .po file - And also remove those entries present in the .po file but not in the templates (because they were removed) - But you want to update some translations with new references and extracted comments - And keep the translations, comments and flags defined in .po file For this scenario, you can use the option `Merge::SCAN_AND_LOAD` with the combination of options to fit this needs (SCAN new entries and LOAD a .po file). ``` $newEntries = $scanner->scanFile('template.php'); $previousEntries = $loader->loadFile('translations.po'); $updatedEntries = $newEntries->mergeWith($previousEntries); ``` gettext language list automatically generated from CLDR data ============================================================ [](#gettext-language-list-automatically-generated-from-cldr-data) Static usage ------------ [](#static-usage) To use the languages data generated from this tool you can use the `bin/export-plural-rules` command. #### Export command line options [](#export-command-line-options) `export-plural-rules` supports the following options: - `--us-ascii`If specified, the output will contain only US-ASCII characters. If not specified, the output charset is UTF-8. - `--languages=[,,...]]``--language=[,,...]]`Export only the specified language codes. Separate languages with commas; you can also use this argument more than once; it's case-insensitive and accepts both '\_' and '-' as locale chunks separator (e.g. we accept `it_IT` as well as `it-it`). If this option is not specified, the result will contain all the available languages. - `--reduce=yes|no`If set to yes the output won't contain languages with the same base language and rules. For instance `nl_BE` (`Flemish`) will be omitted because it's the same as `nl` (`Dutch`). Defaults to `no` if `--languages` is specified, to `yes` otherwise. - `--parenthesis=yes|no`If set to no, extra parenthesis will be omitted in generated plural rules formulas. Those extra parenthesis are needed to create a PHP-compatible formula. Defaults to `yes` - `--output=`If specified, the output will be saved to ``. If not specified we'll output to standard output. #### Export formats [](#export-formats) `export-plural-rules` can generate data in the following formats: - `json`: compressed JSON data ``` export-plural-rules json ``` - `prettyjson`: uncompressed JSON data ``` export-plural-rules prettyjson ``` - `html`: html table ([see the result](https://php-gettext.github.io/Languages/)) ``` export-plural-rules html ``` - `php`: build a php file that can be included ``` export-plural-rules --output=yourfile.php php ``` Then you can use that generated file in your php scripts: ``` $languages = include 'yourfile.php'; ``` - `ruby`: build a ruby file that can be included ``` export-plural-rules --parenthesis=no --output=yourfile.rb ruby ``` Then you can use that generated file in your ruby scripts: ``` require './yourfile.rb' PLURAL_RULES['en'] ``` - `xml`: generate an XML document ([here you can find the xsd XML schema](https://php-gettext.github.io/Languages/GettextLanguages.xsd)) ``` export-plural-rules xml ``` - `po`: generate the gettext .po headers for a single language ``` export-plural-rules po --language=YourLanguageCode ``` Dynamic usage ------------- [](#dynamic-usage) #### With Composer [](#with-composer) You can use [Composer](https://getcomposer.org/) to include this tool in your project. Simply launch `composer require gettext/languages` or add `"gettext/languages": "*"` to the `"require"` section of your `composer.json` file. #### Without Composer [](#without-composer) If you don't use composer in your project, you can download this package in a directory of your project and include the autoloader file: ``` require_once 'path/to/src/autoloader.php'; ``` #### Main methods [](#main-methods) The most useful functions of these tools are the following ``` $allLanguages = Gettext\Languages\Language::getAll(); ... $oneLanguage = Gettext\Languages\Language::getById('en_US'); ... ``` `getAll` returns a list of `Gettext\Languages\Language` instances, `getById` returns a single `Gettext\Languages\Language` instance (or `null` if the specified language identifier is not valid). The main properties of the `Gettext\Languages\Language` instances are: - `id`: the normalized language ID (for instance `en_US`) - `name`: the language name (for instance `American English` for `en_US`) - `supersededBy`: the code of a language that supersedes this language code (for instance, `jw` is superseded by `jv` to represent the Javanese language) - `script`: the script name (for instance, for `zh_Hans` - `Simplified Chinese` - the script is `Simplified Han`) - `territory`: the name of the territory (for instance `United States` for `en_US`) - `baseLanguage`: the name of the base language (for instance `English` for `en_US`) - `formula`: the [gettext formula](https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/Plural-forms.html) to distinguish between different plural rules. For instance `n != 1` - `categories`: the plural cases applicable for this language. It's an array of `Gettext\Languages\Category` instances. Each instance has these properties: - `id`: can be (in this order) one of `zero`, `one`, `two`, `few`, `many` or `other`. The `other` case is always present. - `examples`: a representation of some values for which this plural case is valid (examples are simple numbers like `1` or complex ranges like `0, 2~16, 100, 1000, 10000, 100000, 1000000, โ€ฆ`) Is this data correct? --------------------- [](#is-this-data-correct) Yes - as far as you trust the [Unicode CLDR](http://cldr.unicode.org) project. The conversion from CLDR to gettext includes also [a lot of tests](https://travis-ci.org/php-gettext/Languages) to check the results. And all passes ๐Ÿ˜‰. Reference --------- [](#reference) #### CLDR [](#cldr) The [CLDR specifications](https://unicode.org/reports/tr35/tr35-numbers.html#Language_Plural_Rules) define the following variables to be used in the CLDR plural formulas: - `n`: absolute value of the source number (integer and decimals) (eg: `9.870` => `9.87`) - `i`: integer digits of n (eg: `9.870` => `9`) - `v`: number of visible fraction digits in n, with trailing zeros (eg: `9.870` => `3`) - `w`: number of visible fraction digits in n, without trailing zeros (eg: `9.870` => `2`) - `f`: visible fractional digits in n, with trailing zeros (eg: `9.870` => `870`) - `t`: visible fractional digits in n, without trailing zeros (eg: `9.870` => `87`) - `c`: exponent of the power of 10 used in compact decimal formatting (eg: `98c7` => `7`) - `e`: synonym for `c` #### gettext [](#gettext-1) The [gettext specifications](https://www.gnu.org/savannah-checkouts/gnu/gettext/manual/html_node/Plural-forms.html) define the following variables to be used in the gettext plural formulas: - `n`: unsigned long int ### Conversion CLDR > gettext [](#conversion-cldr--gettext) CLDR variablegettext equivalent`n``n``i``n``v``0``w``0``f`*empty*`t`*empty*`c`*empty*`e`*empty*Parenthesis in ternary operators -------------------------------- [](#parenthesis-in-ternary-operators) The generated gettext formulas contain some extra parenthesis, in order to avoid problems in some programming language. For instance, let's assume we have this formula: `(0 == 0) ? 0 : (0 == 1) ? 1 : 2` - [in C it evaluates to `0`](http://codepad.org/Epw5WkmJ) since is the same as `(0 == 0) ? 0 : ((0 == 1) ? 1 : 2)` - [in Java, it evaluates to `0`](https://ideone.com/vbRHjW) since is the same as `(0 == 0) ? 0 : ((0 == 1) ? 1 : 2)` - [in JavaScript, it evaluates to `0`](https://jsfiddle.net/7fnxa599/) since is the same as `(0 == 0) ? 0 : ((0 == 1) ? 1 : 2)` - [in PHP, it evaluates to `2`](https://3v4l.org/QAAnA) since is the same as `((0 == 0) ? 0 : (0 == 1)) ? 1 : 2` So, in order to avoid problems, instead of a simple `a ? 0 : b ? 1 : 2`the resulting formulas will be in this format: `a ? 0 : (b ? 1 : 2)` Official Documentation ---------------------- [](#official-documentation) The official documentation for Omega is available [here](https://omega-mvc.github.io) Contributing ------------ [](#contributing) If you'd like to contribute to the Omega example application package, please follow our [contribution guidelines](CONTRIBUTING.md). License ------- [](#license) This project is open-source software licensed under the [GNU General Public License v3.0](LICENSE). ### Health Score 42 โ€” FairBetter than 88% of packages Maintenance95 Actively maintained with recent releases Popularity6 Limited adoption so far Community10 Small or concentrated contributor base Maturity51 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 Unknown Total 1 Last Release 49d ago ### Community Maintainers ![](https://avatars.githubusercontent.com/u/254761234?v=4)[Adriano Giovannini](/maintainers/omega-mvc)[@omega-mvc](https://github.com/omega-mvc) --- Top Contributors [![omega-mvc](https://avatars.githubusercontent.com/u/254761234?v=4)](https://github.com/omega-mvc "omega-mvc (8 commits)") --- Tags gettexti10ni18nlocalizationphpphp84translationi18ntranslationJSgettextpomo ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/omega-mvc-gettext/health.svg) ``` [![Health](https://phpackages.com/badges/omega-mvc-gettext/health.svg)](https://phpackages.com/packages/omega-mvc-gettext) ``` ### Alternatives [gettext/gettext PHP gettext manager 70234.0M130](/packages/gettext-gettext)[jms/translation-bundle Puts the Symfony Translation Component on steroids 44311.3M80](/packages/jms-translation-bundle)[sepia/po-parser Gettext \*.PO file parser for PHP. 1281.6M22](/packages/sepia-po-parser)[phpmyadmin/motranslator Translation API for PHP using Gettext MO files 622.0M11](/packages/phpmyadmin-motranslator)[elegantly/laravel-translator All on one translations management for Laravel 6547.8k](/packages/elegantly-laravel-translator)[gettext/php-scanner PHP scanner for gettext 16637.7k19](/packages/gettext-php-scanner) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)