PHPackages                             vertilia/text - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Localization & i18n](/categories/localization)
4. /
5. vertilia/text

ActiveLibrary[Localization & i18n](/categories/localization)

vertilia/text
=============

Translations via gettext and PO format

v1.5.1(2y ago)023.9k—0%1BSD-2-ClausePHPPHP >=7.4

Since Sep 4Pushed 2y ago2 watchersCompare

[ Source](https://github.com/vertilia/text)[ Packagist](https://packagist.org/packages/vertilia/text)[ RSS](/packages/vertilia-text/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (20)Used By (0)

text
====

[](#text)

Translation library based on [gettext](https://www.gnu.org/software/gettext) concept, tools and PO files.

Description
-----------

[](#description)

This library is intended to continue using gettext as project internationalization approach, keeping proven localization methodology but eliminate dependency on complex target system configuration and on `gettext` php extension. This latter may become unsuitable for specific environments.

`xgettext` extractor from standard gettext toolchain does not handle correctly PHP heredoc/nowdoc syntax on all systems. Here we provide a replacement `xtext` script that extracts strings into a POT format, which may be used as a source file for your gettext workflow.

PO catalogue (representing a gettext domain), extracted from the codebase (by standard gettext method or using `xtext`) is then transformed by the bundled `po2php` tool to a native `.php` class. This class keeps translations in memory and implements language-specific rules as native php code.

Simple messages are maintained via the `_()` method, plural forms and contexts are maintained via corresponding `nget()`, `pget()` and `npget()` methods.

Advantages
----------

[](#advantages)

> **From manual:**
> GNU `gettext` is designed to minimize the impact of internationalization on program sources, keeping this impact as small and hardly noticeable as possible. Internationalization has better chances of succeeding if it is very light weighted, or at least, appear to be so, when looking at program sources.

- no need to use constants or other intermediate constructs replacing messages in source code;
- handling of plural forms;
- handling of context-aware functions (`pgettext` family) that are currently missing from php extension;
- no need to install additional locales on target OS or setting environment variables;
- standard translation process based on PO files; multitude of editors or processes may be used;
- translations are stored in `.php` files which allows for a quick autoloading and opcode caching, minimized runtime effort to get translation into memory and finding translation for source string;
- stable and predictable work in multiprocess web environments, not tied to host system configuration and currently installed system locales;
- bundled tools to correctly handle PHP heredoc/nowdoc syntax and to compile .PO files to native php code.

Installation
------------

[](#installation)

```
composer require vertilia/text
```

Usage
-----

[](#usage)

Programming in C with gettext historically consists of the following phases (simplified):

1. define the source messages language used in your code (normally english)
2. use gettext functions in your source code when working with localized messages
    - (without existing translations, gettext functions simply return the passed strings, so the code is already working at this stage, returning english messages in all environments)
3. use gettext utilities to scan your code and extract localized messages, producing (or updating) `.po` text files
    - (`.po` text files contain messages extracted from code, translations to the target language and rules for plural forms of the target language)
4. translate new/updated messages in `.po` file
5. compile text `.po` file into binary `.mo` file
6. copy `.mo` file into your code, so that now gettext functions (mentioned in 2.) could use them to extract translations for their arguments
7. if new language is added to application, assure the corresponding locale is configured on target system

In `Text` we can bypass phases 5., 6. and 7., and compile `.po` files directly into `.php` classes, containing translated strings and plural forms rules for target language.

These generated classes are stored in `locale/` folder and are configured via composer autoloader. They are handled by opcode cache just like other php code and use the lowest footprint at runtime since only need one CRC32 transformation to return existing translation (or a lack of one).

For large codebases, as with normal gettext, you can break down translations on domains, which mostly signifies using different `.po` files per domain.

When you start the project, and while you have no `.po` file yet, you can use the base `\Vertilia\Text\Text` object to provide translated text. It will simply return the passed argument as translated message, which is mostly ok for debugging purposes. Even in its basic form, it will already be smart enough to correctly handle plural forms for English messages:

```