bitcero / gettext

PHP library to collect and manipulate gettext (.po, .mo, .php, .json, etc)

Gettext

Created by Oscar Otero http://oscarotero.com [email protected] (MIT License)

Gettext is a PHP (5.3) library to import/export/edit gettext from PO, MO, PHP, JS files, etc.

v.3.0

The 3.0 version has some changes in the API. See the changelog for more information: https://github.com/oscarotero/Gettext/releases/tag/v3.0

Installation

With composer (recomended):

composer require gettext/gettext

If you don't use composer in your project, you have to download and place this package in a directory of your project. You need to install also gettext/languages. Then, include the autoloaders of both projects in any place of your php code:

include_once "libs/gettext/src/autoloader.php";
include_once "libs/cldr-to-gettext-plural-rules/src/autoloader.php";

Classes and functions

This package contains the following classes:

• Gettext\Translation - A translation definition
• Gettext\Translations - A collection of translations
• Gettext\Extractors\* - Import translations from various sources (po, mo, php, js, etc)
• Gettext\Generators\* - Export translations to various formats (po, mo, php, json, etc)
• Gettext\Translator - To use the translations in your php templates instead the php extension

Usage example

use Gettext\Translations;

//import from a .po file:
$translations = Translations::fromPoFile('locales/gl.po');

//edit some translations:
$translation = $translations->find(null, 'apple');

if ($translation) {
	$translation->setTranslation('Mazá');
}

//export to a php array:
$translations->toPhpArrayFile('locales/gl.php');

If you want use this translations in your php templates without using the native gettext functions:

use Gettext\Translator;

//Create a translator instance
$t = new Translator();

//Load your translations (exported as PhpArray):
$t->loadTranslations('locales/gl.php');

//Use it:
echo $t->gettext('apple'); // "Mazá"

//If you want use global functions:
Translator::initGettextFunctions($t);

echo __('apple'); // "Mazá"

__e('apple'); // "Mazá"

Translation

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

// __construct($context, $original, $plural)
$translation = new Gettext\Translation('comments', 'One comment', '%s comments');

$translation->setTranslation('Un comentario');
$translation->setPluralTranslation('%s comentarios');

$translation->addReference('templates/comments/comment.php', 34);
$translation->addComment('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

The Gettext\Translations class stores a collection of translations:

$translations = new Gettext\Translations();

//You can add new translations using the array syntax
$translations[] = new Gettext\Translation('comments', 'One comment', '%s comments');

//Or using the "insert" method
$insertedTranslation = $translations->insert('comments', 'One comments', '%s comments');

//Find a specific translation
$translation = $translations->find('comments', 'One comments');

//Edit headers, domain, etc
$translations->setHeader('Last-Translator', 'Oscar Otero');
$translations->setDomain('my-blog');

Extractors

The extrators are classes that extract the gettext values from any source and return a Gettext\Translations instance with them. For example, to scan a .po file:

//From a file
$translations = Gettext\Extractors\Po::fromFile('locales/en.po');

//From a string
$string = file_get_contents('locales/en.po');
$translations = Gettext\Extractors\Po::fromString($string);

The available extractors are the following:

• Gettext\Extractors\Po - Gets the strings from PO
• Gettext\Extractors\Mo - Gets the strings from MO
• Gettext\Extractors\PhpCode - To scan a php file looking for all gettext functions (see translator_functions.php)
• Gettext\Extractors\JsCode - To scan a javascript file looking for all gettext functions (the same than PhpCode but for javascript)
• Gettext\Extractors\PhpArray - To get the translations from a php file that returns an array
• Gettext\Extractors\Jed - To scan a json file compatible with the Jed library
• Gettext\Extractors\Blade - To scan a Blade template (For laravel users. Thanks @eusonlito)
• Gettext\Extractors\Twig - To scan a Twig template (Thanks @exnor)
• Gettext\Extractors\JsonDictionary - To get translations from a plain json file with the format {"original": "translation"}

Generators

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

//Save to a file
Gettext\Generators\Po::toFile($translations, 'locales/en.po');

//Return as a string
$content = Gettext\Generators\Po::toString($translations);
$string = file_put_contents('locales/en.po', $content);

The available generators are:

• Gettext\Generators\Mo - Exports to Mo format
• Gettext\Generators\Po - Exports to Po format
• Gettext\Generators\PhpArray - Exports to php code that returns an array with all values
• Gettext\Generators\Jed - Exports to json format compatible with Jed library
• Gettext\Generators\JsonDictionary - Export to plain json with the format {"original": "translation"} (thanks, @gator92)

To ease the work with generators and extractors you can use the magic methods availables in Gettext\Translations that import and export the translations in all these formats:

use Gettext\Translations;

//Import the translations from a .po file
$translations = Translations::fromPoFile('locales/en.po');

//Export to .mo
$translations->toMoFile('locales/en.mo');

To import translations, the methods are static and named from + [Extractor] + [File/String], for example fromPhpArrayFile or fromJsCodeString. To export use the methods named to + [Generator] + [File/String] for example toPhpArrayFile or toPoString.

Translator

The class Gettext\Translator implements the gettext functions in php. Usefult if you don't have the native gettext extension for php or want to avoid problems with it. You can load the translations from a php array file or using a Gettext\Translations instance:

use Gettext\Translator;

//Create a new instance of the translator
$t = new Translator();

//Load the translations using one of the following ways:

// 1. from php files (generated by Gettext\Extractors\PhpArray)
$t->loadTranslations('locales/gl.php');

// 2. using the array directly
$array = include 'locales/gl.php';
$t->loadTranslations($array);

// 3. using a Gettext\Translations instance (slower)
$translations = Gettext\Translations::fromPoFile('locales/gl.po');
$t->loadTranslations($translations);

//Now you can use it in your templates
echo $t->gettext('apple');

To ease the use of translations in your php templates, you can use the provided functions:

//First load the gettext functions and passing the instance
Translator::initGettextFunctions($t);

echo __('apple'); //returns Mazá

__e('apple'); //echo Mazá

You can scan the php files containing these functions and extract the values with the PhpCode extractor:

<!-- index.php -->
<html>
	<body>
		<?php echo __('Hello world'); ?>
	</body>
</html>

Merging translations

To work with different translations you may want merge them in an unique file. There is a way to do this:

//Create a new Translations instances with our translations.

$translations1 = Gettext\Extractors\Po::fromFile('my-file1.po');
$translations2 = Gettext\Extractors\Po::fromFile('my-file2.po');

//Merge one inside other:
$translations1->mergeWith($translations2);

//Now translations1 has all values

The second argument of mergeWith defines how the merge will be done. You can pass one or various of the following predefined constants:

• MERGE_ADD: Adds the translations from translations2 to translations1 if they not exists
• MERGE_REMOVE: Removes the translations in translations1 if they are not in translations2
• MERGE_HEADERS: Merges the headers from translations2 to translations 1
• MERGE_REFERENCES: Merges the references from translations2 to translations1
• MERGE_COMMENTS: Merges the comments from translations2 to translations1
• MERGE_LANGUAGE: Applies the language and plural forms of translations2 to translation1
• MERGE_PLURAL: Translations with the same id but one with plurals and other singular will be merged

Example:

use Gettext\Translations;

//Scan the php code to find the latest gettext translations
$translations = Translations::fromPhpCodeFile('my-templates.php');

//Get the translations of the code that are stored in a po file
$poTranslations = Translations::fromPoFile('locale.po');

//Apply the translations from the po file to the translations, and merges header and comments but not references and without add or remove translations:
$translations->mergeWith($poTranslations, Translations::MERGE_HEADERS | Translations::MERGE_COMMENTS);

//Now save a po file with the result
$translations->toPoFile('locale.po');

Note, if the second argument is not defined, the default is self::MERGE_ADD | self::MERGE_HEADERS | self::MERGE_COMMENTS | self::MERGE_REFERENCES | self::MERGE_PLURAL

Contributors

• @oscarotero (Creator and maintainer)
• @mlocati (Mo generator/extractor, languages, etc)
• @esnoeijs (plural parser)
• @leom (Jed fixes)
• @eusonlito (Blade extractor)
• @exnor (Twig extractor)
• @vvh-empora (fixes)
• and many more...