Chevere

# Translator

The Translator component is in charge of providing generation and loading for translations.

# How it Works

Translator is built on top of gettext (opens new window) and it provides a set of functions (opens new window) that are used to designate translatable strings, which will define a base language translation file which can be used as the base translation for other languages.

WARNING

This implementation doesn't support domain-related gettext functions for translatable strings neither follows gettext directory structure.

# Translatable Functions

All translatable functions (opens new window) are provided at the Chevere\Components\Translator namespace.

# Singular

Singular form expressions can be handled with __ function:

__(message: 'Hi there');
// Hola ahí

# Singular formatting

Formatting based on sprintf (opens new window) is supported with __f function:

__f(message: 'Hi %s', $userFirstName);
// Hola Rodolfo

# Singular replacement

Replacement based on strtr (opens new window) is supported with __t function:

__t(
    message: 'Hi %userFirstName%, %friendName% is now following you!',
    fromTo: [
        '%userFirstName%' => $userFirstName,
        '%friendName%' => $friendName,
    ]
);
// Hola Rodolfo, Bombo Fica ahora te está siguiendo!

# Plural

Expressions that depends on the subject number can be handled with __n, in which is required to pass singular expression, plural expression and the subject count.

__(
    singular: 'file',
    plural: 'files',
    count: $filesCount
);

# Plural formatting

Formatting based on sprintf (opens new window) is supported with __nf function. Passing count determines the singular/plural form to use and $arg is the actual argument passed to sprintf.

__nf(
    singular: '%s file removed',
    plural: '%s files removed',
    count: $filesCount,
    $arg
);

# Plural replacement

Replacement based on strtr (opens new window) is supported with __nt function:

__nt(
    singular: 'Hi %userFirstName%, %friendName% is now following you!',
    plural: 'Hi %userFirstName%, %friendsNames% are now following you!',
    count: $newFollowersCount,
    fromTo: [
        '%userFirstName%' => $userFirstName,
        '%friendName%' => $friendName,
        '%friendsNames%' => $friendsNamesCommaList,
    ]
);

# PoMaker

The PoMaker component is in charge of providing generation of translations in PO File (opens new window) format.

# Creating PoMaker

Pass the locale and domainarguments to construct a PoMaker. For example, to create messages.po for Chilean Spanish:

use Chevere\Components\Translator\PoMaker;

$poMaker = new PoMaker(locale: 'es-CL', domain: 'messages');

# Scan Directory

Method withScannerFor is used to scan a directory for .php files with calls for translatable functions.

$poMaker = $poMaker->withScannerFor(sourceDir: $source);

# Make file

Method make is used to make the .po translation file at {targetDir}/{locale}/{domain}.po file at the target directory.

$poMaker->make(targetDir: $target);

# TranslatorMaker

The TranslatorMaker component is in charge of converting from PO File format to PHP, which is the format that will be actually used at runtime.

# Creating TranslatorMaker

Create TranslatorMaker by passing the sourceDir to read translation .po files, and the targetDir desired to store generated .php translation files.

use Chevere\Components\Translator\TranslatorMaker;

$translatorMaker = new TranslatorMaker(
    sourceDir: $source,
    targetDir: $target
);

# Making PHP Translations

Method withMakeTranslation is used to generate the PHP translation file at {targetDir}/{locale}/{domain}.php.

use Chevere\Components\Translator\TranslatorMaker;

$translatorMaker = $translatorMaker->withMakeTranslation(
    locale: $locale,
    domain: $domain
);

# TranslatorLoader

The TranslatorLoader component is in charge of providing a Translator, which provides PHP translations.

# Creating TranslatorLoader

Create a TranslatorLoader by passing the load directory.

use Chevere\Components\Translator\TranslatorLoader;

$translatorLoader = new TranslatorLoader(loadDir: $dir);

# Get Translator

The getTranslator method allows to get the Translator (opens new window) for the PHP translation file at {loadDir}/{locale}/{domain}.php.

$translator = $translatorLoader->getTranslator(
    locale: 'en-US',
    domain: 'message'
);

# TranslatorInstance

The TranslatorInstance component is in charge of providing a static translator instance.

# Creating TranslatorInstance

A static instance can be provided by creating a new instance:

use Chevere\Components\Translator\TranslatorInstance;

new TranslatorInstance($translator);

This will bind $translator as the runtime translator service.

# Functions

# getTranslator

Function getTranslator allows to get the current registered Translator by TranslatorInstance.

use function Chevere\Components\Translator\getTranslator;

$translator = getTranslator();