Download the PHP package omega-mvc/gettext without Composer

Documentation | Changelog | Contributing | Code of Conduct | License

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

• Installation
• Running Test
• Known issues
• Classes and Functions
  • Usage Example
  • Translation
  • Translations
  • Translator
  • GettextTranslator
  • TranslatorFunctions
• Loaders
  • ArrayLoader
  • JsonLoader
  • MoLoader
  • PoLoader
  • StrictPoLoader
• Generators
  • ArrayGenerator
  • JsonGenerator
  • MoGenerator
  • PoGenerator
• Scanners
  • JsScanner
  • PhpScanner
• Merging Translations

Installation

Running Test

Known issues

When the test suite is run, the summary reports:

These 2 warnings are intentional: two tests (Scanner\CodeScannerTest::testScanFileThrowsWhenFileIsUnreadable and Loader\LoaderEdgesTest::testUnreadableFilesThrow) deliberately create a file with no read permissions to verify that the error is handled correctly (with the expected exception). The warning is therefore a test tool, not a real problem in the code.

Why is the detail suppressed? Not to hide anything, but to avoid bothering users. The test still passes (the exception is thrown as expected) and the warning message adds no useful information to whoever runs the suite.

How to re-enable the detail display. If you want to see the full report of the two warnings (file paths and stack traces), open phpunit.xml.dist and:

1. Set displayDetailsOnTestsThatTriggerWarnings to true.
2. (Recommended) set failOnWarning back to true to make the suite fail in the presence of warnings.

Classes and functions

This package contains the following classes:

• Omega\Gettext\Translation - A translation definition
• Omega\Gettext\Translations - A collection of translations (under the same domain)
• Omega\Gettext\Translator -
• Omega\Gettext\Scanner\* - Scan files to extract translations (php, js, twig templates, ...)
• Omega\Gettext\Loader\* - Load translations from different formats (po, mo, json, ...)
• Omega\Gettext\Generator\* - Export translations to various formats (po, mo, json, ...)

Quick Start

Translation

The Omega\Gettext\Translation class stores all information about a translation: the original text, the translated text, source references, comments, etc.

Translations

The Omega\Gettext\Translations class stores a collection of translations:

Translator

GettextTranslator

The class Omega\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.

TranslatorFunctions

The TranslatorFunctions class is a static registry that binds a translator and a formatter instance, so they can be reached from anywhere in the application:

Applications willing to expose global helper functions (like __()) can build them on top of this registry. The PhpScanner recognizes the standard gettext function names (__, n__, p__, d__...) when extracting translatable strings.

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

JsonLoader

MoLoader

PoLoader

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:

Generators

The generators export a Omega\Gettext\Translations instance to any format (po, mo, etc.).

This package includes the following generators:

• ArrayGenerator
• JsonGenerator
• MoGenerator
• PoGenerator

ArrayGenerator

ArrayGenerator generates PHP array files from gettext translations with optional pretty-printing and strict types.

JsonGenerator

JsonGenerator generates JSON files from gettext translations with configurable JSON options.

MoGenerator

MoGenerator generates binary .mo files from gettext translations, optionally including headers

PoGenerator

PoGenerator generates human-readable .po files from gettext translations.

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

PhpScanner

Merging translations

You will want to update or merge translations. The function mergeWith create a new Translations instance with other translations merged:

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 Omega\Gettext\Merge class, and are the following:

Use the second argument to configure the merging 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).

gettext language list automatically generated from CLDR data

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-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=<LanguageId>[,<LanguageId>,...]] --language=<LanguageId>[,<LanguageId>,...]] 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=<file name> If specified, the output will be saved to <file name>. If not specified we'll output to standard output.

Export formats

export-plural-rules can generate data in the following formats:

• json: compressed JSON data

• prettyjson: uncompressed JSON data

• html: html table (see the result)

• php: build a php file that can be included

  Then you can use that generated file in your php scripts:

• ruby: build a ruby file that can be included

  Then you can use that generated file in your ruby scripts:

• xml: generate an XML document (here you can find the xsd XML schema)

• po: generate the gettext .po headers for a single language

Dynamic usage

With Composer

You can use Composer to include this tool in your project. Simply launch composer require omega-mvc/gettext or add "omega-mvc/gettext": "*" to the "require" section of your composer.json file.

Main methods

The most useful functions of these tools are the following

getAll returns a list of Omega\Gettext\Languages\Language instances, getById returns a single Omega\Gettext\Languages\Language instance (or null if the specified language identifier is not valid).

The main properties of the Omega\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 to distinguish between different plural rules. For instance n != 1
• categories: the plural cases applicable for this language. It's an array of Omega\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?

Yes - as far as you trust the Unicode CLDR project.

The conversion from CLDR to gettext includes also a lot of tests to check the results. And all passes :wink:.

Reference

CLDR

The CLDR specifications 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

The gettext specifications define the following variables to be used in the gettext plural formulas:

• n: unsigned long int

Conversion CLDR > gettext

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 since is the same as (0 == 0) ? 0 : ((0 == 1) ? 1 : 2)
• in Java, it evaluates to 0 since is the same as (0 == 0) ? 0 : ((0 == 1) ? 1 : 2)
• in JavaScript, it evaluates to 0 since is the same as (0 == 0) ? 0 : ((0 == 1) ? 1 : 2)
• in PHP, it evaluates to 2 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

The official documentation for Omega is available here

Contributing

If you'd like to contribute to the Omega example application package, please follow our contribution guidelines.

License

This project is open-source software licensed under the GNU General Public License v3.0.