{"id":19045690,"url":"https://github.com/phpmyadmin/motranslator","last_synced_at":"2025-05-15T13:05:43.808Z","repository":{"id":4191202,"uuid":"52282461","full_name":"phpmyadmin/motranslator","owner":"phpmyadmin","description":"Translation API for PHP using Gettext MO files","archived":false,"fork":false,"pushed_at":"2025-04-01T03:51:02.000Z","size":746,"stargazers_count":56,"open_issues_count":0,"forks_count":23,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-06T14:38:16.309Z","etag":null,"topics":["gettext","mo-files","php","php-gettext","plural-equations"],"latest_commit_sha":null,"homepage":"https://packagist.org/packages/phpmyadmin/motranslator","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/phpmyadmin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-02-22T15:18:05.000Z","updated_at":"2025-04-01T03:51:06.000Z","dependencies_parsed_at":"2023-07-06T08:18:05.837Z","dependency_job_id":"7ad92606-2162-4317-80f0-66ca8fbf37eb","html_url":"https://github.com/phpmyadmin/motranslator","commit_stats":{"total_commits":366,"total_committers":17,"mean_commits":"21.529411764705884","dds":"0.34426229508196726","last_synced_commit":"0260e984d055a78c82545101d20df2febca3c706"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpmyadmin%2Fmotranslator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpmyadmin%2Fmotranslator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpmyadmin%2Fmotranslator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/phpmyadmin%2Fmotranslator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/phpmyadmin","download_url":"https://codeload.github.com/phpmyadmin/motranslator/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254346624,"owners_count":22055808,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gettext","mo-files","php","php-gettext","plural-equations"],"created_at":"2024-11-08T22:51:06.693Z","updated_at":"2025-05-15T13:05:43.760Z","avatar_url":"https://github.com/phpmyadmin.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# motranslator\n\nTranslation API for PHP using Gettext MO files.\n\n[![Test-suite](https://github.com/phpmyadmin/motranslator/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/phpmyadmin/motranslator/actions/workflows/tests.yml?query=branch%3Amaster)\n[![codecov.io](https://codecov.io/github/phpmyadmin/motranslator/coverage.svg?branch=master)](https://codecov.io/github/phpmyadmin/motranslator?branch=master)\n[![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/phpmyadmin/motranslator/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/phpmyadmin/motranslator/?branch=master)\n[![Packagist](https://img.shields.io/packagist/dt/phpmyadmin/motranslator.svg)](https://packagist.org/packages/phpmyadmin/motranslator)\n\n## Features\n\n* All strings are stored in memory for fast lookup\n* Fast loading of MO files\n* Low level API for reading MO files\n* Emulation of Gettext API\n* No use of `eval()` for plural equation\n\n## Limitations\n\n* Default `InMemoryCache` not suitable for huge MO files which you don't want to store in memory\n* Input and output encoding has to match (preferably UTF-8)\n\n## Installation\n\nPlease use [Composer][1] to install:\n\n```sh\ncomposer require phpmyadmin/motranslator\n```\n\n## Documentation\n\nThe API documentation is available at \u003chttps://develdocs.phpmyadmin.net/motranslator/\u003e.\n\n## Object API usage\n\n```php\n// Create loader object\n$loader = new PhpMyAdmin\\MoTranslator\\Loader();\n\n// Set locale\n$loader-\u003esetlocale('cs');\n\n// Set default text domain\n$loader-\u003etextdomain('domain');\n\n// Set path where to look for a domain\n$loader-\u003ebindtextdomain('domain', __DIR__ . '/data/locale/');\n\n// Get translator\n$translator = $loader-\u003egetTranslator();\n\n// Now you can use Translator API (see below)\n```\n\n## Low level API usage\n\n```php\n// Directly load the mo file\n// You can use null to not load a file and the use a setter to set the translations\n$cache = new PhpMyAdmin\\MoTranslator\\Cache\\InMemoryCache(new PhpMyAdmin\\MoTranslator\\MoParser('./path/to/file.mo'));\n$translator = new PhpMyAdmin\\MoTranslator\\Translator($cache);\n\n// Now you can use Translator API (see below)\n```\n\n## Translator API usage\n\n```php\n// Translate string\necho $translator-\u003egettext('String');\n\n// Translate plural string\necho $translator-\u003engettext('String', 'Plural string', $count);\n\n// Translate string with context\necho $translator-\u003epgettext('Context', 'String');\n\n// Translate plural string with context\necho $translator-\u003enpgettext('Context', 'String', 'Plural string', $count);\n\n// Get the translations\necho $translator-\u003egetTranslations();\n\n// All getters and setters below are more to be used if you are using a manual loading mode\n// Example: $translator = new PhpMyAdmin\\MoTranslator\\Translator(null);\n\n// Set a translation\necho $translator-\u003esetTranslation('Test', 'Translation for \"Test\" key');\n\n// Set translations\necho $translator-\u003esetTranslations([\n  'Test' =\u003e 'Translation for \"Test\" key',\n  'Test 2' =\u003e 'Translation for \"Test 2\" key',\n]);\n\n// Use the translation\necho $translator-\u003egettext('Test 2'); // -\u003e Translation for \"Test 2\" key\n```\n\n## Gettext compatibility usage\n\n```php\n// Load compatibility layer\nPhpMyAdmin\\MoTranslator\\Loader::loadFunctions();\n\n// Configure\n_setlocale(LC_MESSAGES, 'cs');\n_textdomain('phpmyadmin');\n_bindtextdomain('phpmyadmin', __DIR__ . '/data/locale/');\n_bind_textdomain_codeset('phpmyadmin', 'UTF-8');\n\n// Use functions\necho _gettext('Type');\necho __('Type');\n\n// It also support other Gettext functions\n_dnpgettext($domain, $msgctxt, $msgid, $msgidPlural, $number);\n_dngettext($domain, $msgid, $msgidPlural, $number);\n_npgettext($msgctxt, $msgid, $msgidPlural, $number);\n_ngettext($msgid, $msgidPlural, $number);\n_dpgettext($domain, $msgctxt, $msgid);\n_dgettext($domain, $msgid);\n_pgettext($msgctxt, $msgid);\n```\n\n## Using APCu-backed cache\n\nIf you have the [APCu][5] extension installed you can use it for storing the translation cache. The `.mo` file\nwill then only be loaded once and all processes will share the same cache, reducing memory usage and resulting in\nperformance comparable to the native `gettext` extension.\n\nIf you are using `Loader`, pass it an `ApcuCacheFactory` _before_ getting the translator instance:\n\n```php\nPhpMyAdmin\\MoTranslator\\Loader::setCacheFactory(\n    new PhpMyAdmin\\MoTranslator\\Cache\\AcpuCacheFactory()\n);\n$loader = new PhpMyAdmin\\MoTranslator\\Loader();\n\n// Proceed as before \n```\n\nIf you are using the low level API, instantiate the `ApcuCache` directly:\n\n```php\n$cache = new PhpMyAdmin\\MoTranslator\\Cache\\ApcuCache(\n    new PhpMyAdmin\\MoTranslator\\MoParser('./path/to/file.mo'),\n    'de_DE',     // the locale\n    'phpmyadmin' // the domain\n);\n$translator = new PhpMyAdmin\\MoTranslator\\Translator($cache);\n\n// Proceed as before\n```\n\nBy default, APCu will cache the translations until next server restart and prefix the cache entries with `mo_` to\navoid clashes with other cache entries. You can control this behaviour by passing `$ttl` and `$prefix` arguments, either\nto the `ApcuCacheFactory` or when instantiating `ApcuCache`:\n\n```php\nPhpMyAdmin\\MoTranslator\\Loader::setCacheFactory(\n    new PhpMyAdmin\\MoTranslator\\Cache\\AcpuCacheFactory(\n        3600,     // cache for 1 hour\n        true,     // reload on cache miss\n        'custom_' // custom prefix for cache entries\n    )\n);\n$loader = new PhpMyAdmin\\MoTranslator\\Loader();\n\n// or...\n\n$cache = new PhpMyAdmin\\MoTranslator\\Cache\\ApcuCache(\n    new PhpMyAdmin\\MoTranslator\\MoParser('./path/to/file.mo'),\n    'de_DE',\n    'phpmyadmin',\n    3600,     // cache for 1 hour\n    true,     // reload on cache miss\n    'custom_' // custom prefix for cache entries\n);\n$translator = new PhpMyAdmin\\MoTranslator\\Translator($cache);\n```\n\nIf you receive updated translation files you can load them without restarting the server using the low-level API:\n\n```php\n$parser = new PhpMyAdmin\\MoTranslator\\MoParser('./path/to/file.mo');\n$cache = new PhpMyAdmin\\MoTranslator\\Cache\\ApcuCache($parser, 'de_DE', 'phpmyadmin');\n$parser-\u003eparseIntoCache($cache);\n```\n\nYou should ensure APCu has enough memory to store all your translations, along with any other entries you use it \nfor. If an entry is evicted from cache, the `.mo` file will be re-parsed, impacting performance. See the \n`apc.shm_size` and `apc.shm_segments` [documentation][6] and monitor cache usage when first rolling out.\n\nIf your `.mo` files are missing lots of translations, the first time a missing entry is requested the `.mo` file \nwill be re-parsed. Again, this will impact performance until all the missing entries are hit once. You can turn off this\nbehaviour by setting the `$reloadOnMiss` argument to `false`. If you do this it is _critical_ that APCu has enough \nmemory, or users will see untranslated text when entries are evicted.\n\n## History\n\nThis library is based on [php-gettext][2]. It adds some performance\nimprovements and ability to install using [Composer][1].\n\n## Motivation\n\nMotivation for this library includes:\n\n* The [php-gettext][2] library is not maintained anymore\n* It doesn't work with recent PHP version (phpMyAdmin has patched version)\n* It relies on `eval()` function for plural equations what can have severe security implications, see [CVE-2016-6175][4]\n* It's not possible to install it using [Composer][1]\n* There was place for performance improvements in the library\n\n### Why not to use native gettext in PHP?\n\nWe've tried that, but it's not a viable solution:\n\n* You can not use locales not known to system, what is something you can not\n  control from web application. This gets even more tricky with minimalist\n  virtualisation containers.\n* Changing the MO file usually leads to PHP segmentation fault. It (or rather\n  Gettext library) caches headers of MO file and if it's content is changed\n  (for example new version is uploaded to server) it tries to access new data\n  with old references. This is bug known for ages:\n  https://bugs.php.net/bug.php?id=45943\n\n### Why use Gettext and not JSON, YAML or whatever?\n\nWe want translators to be able to use their favorite tools and we want us to be\nable to use wide range of tools available with Gettext as well such as \n[web based translation using Weblate][3]. Using custom format usually adds\nanother barrier for translators and we want to make it easy for them to\ncontribute.\n\n[1]:https://getcomposer.org/\n[2]:https://launchpad.net/php-gettext\n[3]:https://weblate.org/\n[4]: https://www.cve.org/CVERecord?id=CVE-2016-6175\n[5]:https://www.php.net/manual/en/book.apcu.php\n[6]:https://www.php.net/manual/en/apcu.configuration.php\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphpmyadmin%2Fmotranslator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fphpmyadmin%2Fmotranslator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fphpmyadmin%2Fmotranslator/lists"}