feat: Add context-aware gettext functions

[HB9HIL]

Context-aware gettext functions are not part of the default php-gettext extension. So wouldn't it be nice if this Gettext Class for Codeigniter 4 supports those aswell?

This PR implements the gettext context functions and are used the following way:

Four context-aware gettext functions have been added to handle translations where the same string may have different meanings depending on context:

• pgettext() - Context-aware gettext
• npgettext() - Context-aware plural gettext
• dpgettext() - Context-aware gettext with domain
• dnpgettext() - Context-aware plural gettext with domain

Usage Examples

pgettext($context, $message)

Translates a message within a specific context.

// "lead" can mean different things
echo pgettext('verb', 'lead');      // To lead a team
echo pgettext('noun', 'lead');      // The metal lead

npgettext($context, $singular, $plural, $count)

Handles plural forms with context.

$count = 3;
echo npgettext('email', '%d message', '%d messages', $count);
// Email context: "3 messages"

echo npgettext('chat', '%d message', '%d messages', $count);
// Chat context: "3 chats" or "3 texts"

dpgettext($domain, $context, $message)

Translates with both domain and context.

// Using different translation domains
echo dpgettext('admin', 'button', 'Delete');    // "Remove permanently"
echo dpgettext('frontend', 'button', 'Delete'); // "Move to trash"

dnpgettext($domain, $context, $singular, $plural, $count)

Combines domain, context, and plural handling.

$files = 5;
echo dnpgettext('filesystem', 'trash', '%d file', '%d files', $files);
// Result: "5 files in trash"

echo dnpgettext('filesystem', 'upload', '%d file', '%d files', $files);
// Result: "5 files uploaded"

Why use context?

Context prevents translation conflicts when the same word has different meanings:

// Without context - ambiguous
echo _('Open');  // Open a file? Open status? Open source?

// With context - precise
echo pgettext('verb', 'Open');       // "Open the file"
echo pgettext('adjective', 'Open');  // "Status: Open"

Checklist:

• Securely signed commits
• Component(s) with PHPDoc blocks, only if necessary or adds value
• Unit testing, with >80% coverage
• User guide updated
• Conforms to style guide

[michalsn]

@HB9HIL Thanks for this! I have a few follow-ups:

Could you try running composer cs-fix and then address the suggestions reported by Rector?

It would be good to validate the domain used in these new methods, similar to what we already do in setDomain(). We could probably extract that check into a separate method and reuse it where needed.

You added a nice explanation of the new methods in the PR description - could we also include that in the README? At the moment, only one of the new functions is documented there.

[HB9HIL]

Hello @michalsn

Thx for the nice feedback! I fixed the things you mentiond

• cs-fix wanted some prettied doc blocks (fixed)
• I extracted the domain verification in a private and verified the domains in the context aware domain functions
• Rector missed strict declaration in the test
• I added all context aware functions to the readme and explained final usage with sprintf()

😄

[HB9HIL]

PS: I played a bit around with tests for the context-aware functions. But I'm not 100% how to achive that. Due to the nature of gettext it could be hard to setup a working test environment. One solution could be to make those functions in a dedicated namespace available as stub functions which could work pretty good. But I don't have that much experience with that and it's more trial and error than something I can add to this PR in good conscience.

[michalsn]

That's fine. Thanks!