# Translator

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

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

# 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.

TIP

Using services like OneSky (opens new window) you can allow others to easily collaborate with translations.

# Translatable Functions

All translatable functions (opens new window) are provided at the global 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. Note that 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();