README.md
1# motranslator
2
3Translation API for PHP using Gettext MO files.
4
5[](https://travis-ci.org/phpmyadmin/motranslator)
6[](https://codecov.io/github/phpmyadmin/motranslator?branch=master)
7[](https://scrutinizer-ci.com/g/phpmyadmin/motranslator/?branch=master)
8[](https://packagist.org/packages/phpmyadmin/motranslator)
9
10## Features
11
12* All strings are stored in memory for fast lookup
13* Fast loading of MO files
14* Low level API for reading MO files
15* Emulation of Gettext API
16* No use of `eval()` for plural equation
17
18## Limitations
19
20* Not suitable for huge MO files which you don't want to store in memory
21* Input and output encoding has to match (preferably UTF-8)
22
23## Installation
24
25Please use [Composer][1] to install:
26
27```
28composer require phpmyadmin/motranslator
29```
30
31## Documentation
32
33The API documentation is available at
34<https://develdocs.phpmyadmin.net/motranslator/>.
35
36
37## Object API usage
38
39```php
40// Create loader object
41$loader = new PhpMyAdmin\MoTranslator\Loader();
42
43// Set locale
44$loader->setlocale('cs');
45
46// Set default text domain
47$loader->textdomain('domain');
48
49// Set path where to look for a domain
50$loader->bindtextdomain('domain', __DIR__ . '/data/locale/');
51
52// Get translator
53$translator = $loader->getTranslator();
54
55// Now you can use Translator API (see below)
56```
57
58## Low level API usage
59
60```php
61// Directly load the mo file
62$translator = new PhpMyAdmin\MoTranslator\Translator('./path/to/file.mo');
63
64// Now you can use Translator API (see below)
65```
66
67## Translator API usage
68
69```php
70// Translate string
71echo $translator->gettext('String');
72
73// Translate plural string
74echo $translator->ngettext('String', 'Plural string', $count);
75
76// Translate string with context
77echo $translator->pgettext('Context', 'String');
78
79// Translate plural string with context
80echo $translator->npgettext('Context', 'String', 'Plural string', $count);
81```
82
83## Gettext compatibility usage
84
85```php
86// Load compatibility layer
87PhpMyAdmin\MoTranslator\Loader::loadFunctions();
88
89// Configure
90_setlocale(LC_MESSAGES, 'cs');
91_textdomain('phpmyadmin');
92_bindtextdomain('phpmyadmin', __DIR__ . '/data/locale/');
93_bind_textdomain_codeset('phpmyadmin', 'UTF-8');
94
95// Use functions
96echo _gettext('Type');
97echo __('Type');
98
99// It also support other Gettext functions
100_dnpgettext($domain, $msgctxt, $msgid, $msgidPlural, $number);
101_dngettext($domain, $msgid, $msgidPlural, $number);
102_npgettext($msgctxt, $msgid, $msgidPlural, $number);
103_ngettext($msgid, $msgidPlural, $number);
104_dpgettext($domain, $msgctxt, $msgid);
105_dgettext($domain, $msgid);
106_pgettext($msgctxt, $msgid);
107```
108
109## History
110
111This library is based on [php-gettext][2]. It adds some performance
112improvements and ability to install using [Composer][1].
113
114## Motivation
115
116Motivation for this library includes:
117
118* The [php-gettext][2] library is not maintained anymore
119* It doesn't work with recent PHP version (phpMyAdmin has patched version)
120* It relies on `eval()` function for plural equations what can have severe security implications, see CVE-2016-6175
121* It's not possible to install it using [Composer][1]
122* There was place for performance improvements in the library
123
124### Why not to use native gettext in PHP?
125
126We've tried that, but it's not a viable solution:
127
128* You can not use locales not known to system, what is something you can not
129 control from web application. This gets even more tricky with minimalist
130 virtualisation containers.
131* Changing the MO file usually leads to PHP segmentation fault. It (or rather
132 Gettext library) caches headers of MO file and if it's content is changed
133 (for example new version is uploaded to server) it tries to access new data
134 with old references. This is bug known for ages:
135 https://bugs.php.net/bug.php?id=45943
136
137### Why use Gettext and not JSON, YAML or whatever?
138
139We want translators to be able to use their favorite tools and we want us to be
140able to use wide range of tools available with Gettext as well such as
141[web based translation using Weblate][3]. Using custom format usually adds
142another barrier for translators and we want to make it easy for them to
143contribute.
144
145[1]:https://getcomposer.org/
146[2]:https://launchpad.net/php-gettext
147[3]:https://weblate.org/
148
){kind=link}
){kind=link}
){kind=link}
){kind=link}