<commit_before>Gettext
=======

[![Build Status](https://travis-ci.org/oscarotero/Gettext.png?branch=master)](https://travis-ci.org/oscarotero/Gettext)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/oscarotero/Gettext/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/oscarotero/Gettext/?branch=master)

Created by <NAME> <http://oscarotero.com> <<EMAIL>> (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


## Usage example

```php
//Include the autoloader if you don't use composer or PSR-4 loader
include('src/autoloader.php');

//scan a Po file:
$translations = Gettext\Translations::fromPoFile('locales/gl.po');

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

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

//Export to PhpArray:
$translations->toPhpArrayFile('locales/gl.php');

//Create a translator for your php templates
$t = new Gettext\Translator();

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

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

//Use the global functions:
Gettext\Translator::initGettextFunctions($t);

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

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

## Classes and functions

This package contains the following classes:

* `Gettext\Translation` - A translation definition
* `Gettext\Translations` - A collection of translations
* `Gettext\Translator` - Emulate gettext functions in your php templates
* `Gettext\Extractors\*` - Extract gettext values from various sources
* `Gettext\Generators\*` - Generate gettext formats

And the file `translator_functions.php` that provide the gettext functions to use in your templates.


## Translation

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

```php
// __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:

```php
$translations = new Gettext\Translations();

//You can add new tranlations using the array syntax
$tranlations[] = 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, the domain value, etc
$translations->setHeader('Last-Translator', '<NAME>');
$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:

```php
//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](http://slexaxton.github.com/Jed/)
* `Gettext\Extractors\Blade` - To scan a Blade template (For laravel users. Thanks @eusonlito)

## Generators

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

```php
//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](http://slexaxton.github.com/Jed/)

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:<commit_msg>updated docs<commit_after>Gettext
=======

[![Build Status](https://travis-ci.org/oscarotero/Gettext.png?branch=master)](https://travis-ci.org/oscarotero/Gettext)
[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/oscarotero/Gettext/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/oscarotero/Gettext/?branch=master)

Created by <NAME> <http://oscarotero.com> <<EMAIL>> (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


## Usage example

```php
//Include the autoloader if you don't use composer or PSR-4 loader
include('src/autoloader.php');

//scan a Po file:
$translations = Gettext\Translations::fromPoFile('locales/gl.po');

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

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

//Export to PhpArray:
$translations->toPhpArrayFile('locales/gl.php');

//Create a translator for your php templates
$t = new Gettext\Translator();

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

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

//Use the global functions:
Gettext\Translator::initGettextFunctions($t);

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

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

## Classes and functions

This package contains the following classes:

* `Gettext\Translation` - A translation definition
* `Gettext\Translations` - A collection of translations
* `Gettext\Translator` - Emulate gettext functions in your php templates
* `Gettext\Extractors\*` - Extract gettext values from various sources
* `Gettext\Generators\*` - Generate gettext formats

And the file `translator_functions.php` that provide the gettext functions to use in your templates.


## Translation

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

```php
// __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:

```php
$translations = new Gettext\Translations();

//You can add new tranlations using the array syntax
$tranlations[] = 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, the domain value, etc
$translations->setHeader('Last-Translator', '<NAME>');
$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:

```php
//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](http://slexaxton.github.com/Jed/)
* `Gettext\Extractors\Blade` - To scan a Blade template (For laravel users. Thanks [@eusonlito](https://github.com/eusonlito))
* `Gettext\Extractors\JsonDictionary` - To get translations from a plain json file with the format `{"original": "translation"}`

## Generators

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

```php
//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](http://slexaxton.github.com/Jed/)
* `Gettext\Generators\JsonDictionary` - Export to plain json with the format `{"original": "translation"}` (thanks, [@gator92](https://github.com/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:
{'fraction_non_alphanumeric': 0.1361344537815126, 'fraction_numerical': 0.002427637721755369, 'mean_word_length': 5.249124854142357, 'pattern_counts': {'":': 2, '<': 13, '<?xml version=': 0, '>': 45, 'https://': 12, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '583889', 'n_tokens_mistral': 3356, 'n_tokens_neox': 3264, 'n_words': 1014}