Translator
Mautic leverages a decorated Symfony Translator service for translations.
Visit Translating Mautic for information on how to translate Core. Plugins must include their own translations.
Translation file and directory structure
Translations are INI files organized in the following directory structure for Core bundles and Plugins:
Translations/
{locale}/
{:ref:`domain<Translation domains>`}.ini
Note
All Core bundles and Plugins must include translations for the US English, en_US, locale.
Mautic loads translations through \Mautic\CoreBundle\Loader\TranslationLoader
where it loads translations in the following order. Note that the value for the key loaded last is what Mautic uses.
{bundle}/Translations/{locale}/
themes/{default_theme}/translations/
translations/{locale}/
translations/overrides/{locale}/
Note
The loader finds and loads all INI files within those directories or their subdirectories.
Translation domains
Translation domains organize translations into files. The following are defined by Mautic but the Plugin can define and use its own domains by passing the domain into the trans
method.
Domain |
Description |
---|---|
|
Default domain for translations. |
|
Default domain for translations for the |
|
Default domain for constraint messages for validations in Symfony form field types. |
Translation strings
Translations are key/value pairs in the INI
format. There is no hard and fast rule but, typically, Mautic uses periods, .
, to separate domains in translation keys and underscores, _
, to separate words. You can also use placeholders for the Translator service to replace with values given by the calling code. Placeholders typically are wrapped in percent signs, %
.
helloworld.greeting="Welcome %name%!"
helloworld.form.world_select="Select the world you want to visit."
helloworld.form.world_select.tooltip="Note that most are visit at your own risk!"
helloworld.moons.number_of_moons="{0}%world% has no moons|{1}%world% has one moon|]1,Inf[ %world% has %count% moons"
Using the Translator service
Plugins have access to service by passing translator
as a service dependency. Type-hint the argument in the service’s construct with Symfony\Component\Translation\TranslatorInterface
.
In PHP templates, use $view['translator']
to access the Translator service.
- Mautic\CoreBundle\Translation\Translator
- trans(string $id[, array $parameters = [], ?string $domain = null, ?string $locale = null])
Returns the translation for the given key.
- Parameters:
$parameters (
array
) – Parameters as key/value pairs to populate placeholders in the translation. Note that Symfony has deprecated transChoice() in favor of using this method plus defining the key%count%
in$parameters
. For example,echo $translator->trans('helloworld.number_of_moons', ['%count%' => 1, '%world% => 'Earth']);
with the translation,"helloworld.number_of_moons="{0}%world% has no moons|{1}%world% has one moon|]1,Inf[ %world% has %count% moons"
.$domain (
string|null
) – Specific domain to look for the translation key. Defaults tomessages
ifNULL
.$locale (
string|null
) – Specific locale to look for the translation key. Defaults to system or user configured locale.
- Returns:
Returns the translated string if the key is found. Otherwise, an empty string.
- Return type:
string
- transConditional(string $preferred, string $alternative[, array $parameters = [], ?string $domain = null, ?string $locale = null])
Translates the preferred key if it exists and the alternate key if it does not.
- Parameters:
$preferred (
string
) – Preferred translation key.$alternative (
string
) – Alternate translation key if the preferred does does not exist.$parameters (
array
) – Parameters as key/value pairs to populate placeholders in the translation.$domain (
string|null
) – Specific domain to look for the translation key. Defaults tomessages
ifNULL
.$locale (
string|null
) – Specific locale to look for the translation key. Defaults to system or user configured locale.
- Returns:
Returns the translated string if the key is found. Otherwise, an empty string.
- Return type:
string
- hasId(string $id[, ?string $domain = null, ?string $local = null])
Checks to see if a translation key exists.
- Parameters:
$id (
string
) – Translation key. For example,mautic.core.empty
.$domain (
string|null
) – Specific domain to search. Defaults tomessages
ifNULL
.$locale (
string|null
) – Specific locale to search. Defaults to system or user configured locale.
- Returns:
TRUE
if the translation key exists.FALSE
otherwise.- Return type:
boolean