# 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 domain
arguments 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();