README

Implementation of context functions for the PHP gettext extension

About

PHP still lacks full support for gettext, because it does not implement the context functions. Until this is sorted out, you can use this package to add context support to your localization efforts.

For example, in English, both persons and products have a "name" attribute. So using a simple gettext:

echo _('Name');

... would yield "Ime" in Slovenian, which is wrong.

To solve this, you can use a context function provided by this package:

echo pgettext('Person', 'Name'); // Echoes "Ime"
echo pgettext('Product', 'Name'); // Echoes "Naziv"

Requirements

PHP >= 7.4
gettext PHP extension

It can be used on lower versions of PHP, but you won't be able to install it with composer (or run tests).

This package is tested for Linux, but it should work for other systems too. Any Windows and Mac feedback is highly welcome. It would be great if you could make a pull request for testing on those platforms (including the GitHub workflow).

Installing

Download it with composer: composer require datalinx/gettext-context
Include the vendor/datalinx/gettext-context/src/gettext-context.php file when you need it*

* It's not added to the autoload directive, since you might not need or want to always include it in runtime. If you want to always load it, just add the source file to your composer.json autoload files list:

{
    "autoload": {
        "files": [
            "vendor/datalinx/gettext-context/src/gettext-context.php"
        ]
    }
}

Usage

See the documented src/gettext-context.php file for the list of functions and their parameters.

Extracting messages with context support

With xgettext

You can add extra keyword parameters to your xgettext call to include the context functions. For example, this would be used in our package:

xgettext --force-po --keyword=pgettext:1c,2 --keyword=npgettext:1c,2,3 --keyword=dpgettext:2c,3 --keyword=dnpgettext:2c,3,4 -c -o messages.po tests/Unit/Test.php

With Poedit

If you're using Poedit, add the following keywords in your Catalog > Properties > Sources Keywords:

pgettext:1c,2
npgettext:1c,2,3
dpgettext:2c,3
dnpgettext:2c,3,4

Then run the "Update from code" procedure :)

Contributing

If you have some suggestions how to make this package better, please open an issue or even better, submit a pull request.

Should you want to contribute, please see the development guidelines in the DataLinx PHP package template.

Changelog

All notable changes to this project are automatically documented in the CHANGELOG.md file using the release workflow, based on the release-please GitHub action.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

For all this to work, commit messages must follow the Conventional commits specification, which is also enforced by a Git hook.

Credits

This answer on Stack Overflow for the implementation.
This comment on the PHP documentation for the messages extraction fix.

datalinx / gettext-context

Maintainers

Details