Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 30 ยท Quality and Security

Translations and Multilingual Modules

Make a PrestaShop module speak every language: trans() domains, Smarty and Twig translation, XLIFF catalogs, multilingual fields and currency formatting, with a runnable translator.

A PrestaShop store often sells in several languages and currencies at once, and your module is part of every page the customer sees. If you hard-code English strings, the shop owner in Madrid has no way to change them, and the shop is stuck with a half-translated checkout. Translation in PrestaShop is built from three separate ideas: translating the words your code displays, storing content that the merchant enters in several languages, and showing prices in the right currency and format.

This lesson covers all three. You will learn what a translation domain is, how to translate in PHP, Smarty and Twig, how translation catalogs are stored, how multilingual settings and database fields work, and how to format money. The real code is read-only; the runnable stand-ins mimic a translator and a multilingual lookup so you can see the rules working. If you have not yet seen how configuration values are stored, read A Module Configuration Page first.

Domains: where a string lives

Modern PrestaShop (1.7.6 and later, including 8 and 9) translates strings with a Symfony-style translator. Every call names a domain, which groups related strings. A domain looks like dotted words, for example Modules.Demopay.Shop.

  • Core domains start with a prefix such as Admin. (back office) or Shop. (front office), for example Admin.Actions for words like Save and Delete, Admin.Global for common labels, and Shop.Theme.Global for shared theme words.
  • Module domains start with Modules., followed by the module name with a capital first letter, followed by a context word. By convention the context is Admin for strings shown in the back office and Shop for strings shown to customers.

Splitting by context matters, because the back office and the shop can have different default languages, and translators work on one area at a time.

Reuse core strings when they exist. A "Save" button should use Admin.Actions, so it is already translated in every language the shop has installed. Only strings that are specific to your module go into your own domains.

Translating in PHP, Smarty and Twig

In a class that extends Module (or a front controller of a module), use $this->trans(). The arguments are the source text (in English), a list of replacements, and the domain.

PHP
$title = $this->trans('Delivery estimate', [], 'Modules.Deliverynotice.Shop');

$greeting = $this->trans(
    'Hello %name%, your parcel leaves today.',
    ['%name%' => $customer->firstname],
    'Modules.Deliverynotice.Shop'
);

Placeholders are written between percent signs and filled from the array. Never glue a sentence together from several translated pieces, because word order differs between languages. Translate the whole sentence with a placeholder instead.

In Smarty templates use the l function with the d parameter for the domain:

SMARTY
<p>{l s='Delivery estimate' d='Modules.Deliverynotice.Shop'}</p>
<p>{l s='Hello %name%, your parcel leaves today.' sprintf=['%name%' => $firstname] d='Modules.Deliverynotice.Shop'}</p>

In Twig templates of the Symfony back office use the trans filter:

TWIG
<h3>{{ 'Delivery settings'|trans({}, 'Modules.Deliverynotice.Admin') }}</h3>

Two rules keep your strings translatable. First, the source text must be a literal. The scanner that collects strings from your files reads the code without running it, so $this->trans($variable, ...) is invisible to it. Second, use the exact same source text and domain in every place that should share a translation.

How translations are stored

When a string is not found in any catalog, PrestaShop shows the source text, which is why English is the fallback. Catalogs come from two places:

  1. Core and module XLIFF files. XLIFF is an XML format for translations. For modules written in the modern style, translations are kept in files inside the module's translations/ folder, organized by locale, with one file per domain. The names are derived from the domain and the locale, so check the example in the official modules you have installed for the exact layout of your version.
  2. The shop database. Merchants can edit translations in the back office (International, Translations). Edited strings are stored in the database and override the files, so a merchant can rephrase a message without touching your code.

Older modules use a single PHP array file per language, translations/fr.php, filled with keys that contain a hash of the string. That format is still read for backwards compatibility, but new code should use domains and the translator, because the old key format is hard to generate by hand and only tied to one file.

flowchart LR
    A["trans('Hello', [], domain)"] --> B{"In shop database?"}
    B -- yes --> R["Show merchant's text"]
    B -- no --> C{"In module XLIFF catalog?"}
    C -- yes --> R2["Show catalog text"]
    C -- no --> D["Show the source text"]

Lookup order in simplified form: merchant edits, then catalog files, then the English source.

The stand-in translator below keeps catalogs per locale and domain, applies the same fallback chain, and fills %name% placeholders. It is a teaching model, not PrestaShop's translator, which is the Symfony component with more features.

PHP Stand-in: a translator with domains and fallback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice that Spanish has no translation for the greeting, so it falls back to English, and German has none at all. This is the behavior you want: the page still works, and the missing strings are easy to find.

Multilingual settings and database fields

Some text is not code but content: a banner message the merchant types in the module's configuration page, or a product-related label stored in your own table. That content must be stored once per language.

For simple settings, Configuration supports per-language values. You save an array keyed by language id, and read one value for the language you need:

PHP
$values = [];
foreach (Language::getLanguages(false) as $language) {
    $values[(int) $language['id_lang']] = Tools::getValue('NOTICE_TEXT_' . (int) $language['id_lang']);
}
Configuration::updateValue('DELIVERYNOTICE_TEXT', $values, true);

$text = Configuration::get('DELIVERYNOTICE_TEXT', (int) $this->context->language->id);

The third argument true allows HTML in the value, so only use it for settings that only administrators can change and always escape or sanitize on output. In the configuration form, an input marked 'lang' => true makes HelperForm show a language switcher and submit one field per language. The form is built as in A Module Configuration Page.

For records in your own table, ObjectModel handles the split for you. Fields flagged with 'lang' => true in the $definition array live in a second table named like the main one with a _lang suffix, keyed by object id and language id (and shop id for multistore). You read the title for the current language with $object->title[$idLang], and when you build entities yourself, ObjectModel and Entities shows the full definition. Always provide a value for every installed language, or fall back to the shop's default language, because a language can be added after your module is installed.

The stand-in stores titles per language and chooses the best one: the requested language, then the shop default language, then any value.

PHP Stand-in: multilingual rows with a default-language fallback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The last query shows a useful habit: when a language is added after install, find the rows that lack text and fill them, perhaps from the default language.

Currencies and formatting

A module that prints a price must not guess the symbol or the separators. Each currency has an id, an ISO code and display rules, and each language has its own number format: 1,234.50 in English but 1 234,50 in French. In current PrestaShop versions you format prices with the locale that matches the shop context:

PHP
$locale = $this->context->getCurrentLocale();
$formatted = $locale->formatPrice(29.9, $this->context->currency->iso_code);

This returns the text with the right symbol, separators and symbol position for the customer's language. Older code uses Tools::displayPrice(), which is deprecated in newer versions, so prefer the locale. Keep amounts as numbers or integer cents in your own logic and format only at the last moment, as explained in Money as Integers and Currencies and Localization.

For payment or shipping modules the module can be limited to some currencies: set $this->currencies = true and $this->currencies_mode = 'checkbox' in the constructor so the merchant chooses them, as shown in Payment Modules.

Write the English source string once, in a short, complete sentence, and let translators do the rest. Avoid text that depends on a number, like "1 items". Pass the number as a placeholder and write a sentence that works for the plural forms in your target languages, or use a message format that supports plurals.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which domain follows the convention for a back-office string of a module named Deliverynotice?

    Module domains start with Modules, then the capitalized module name, then Admin or Shop for the area where the text is displayed.
  2. 2. Why should you translate a whole sentence with a placeholder instead of joining translated fragments?

    A sentence built from pieces forces one word order on every language. A single string with %name% lets translators arrange the words naturally.
  3. 3. A string has no translation for the customer's language. What does PrestaShop display?

    The source text is the fallback, which is why you write it as a clear English sentence.
  4. 4. How are values of a multilingual setting saved with Configuration::updateValue()?

    Pass an array of language id to value. Configuration::get() with a language id then returns the value for that language.
  5. 5. Why does $this->trans($variable, [], $domain) cause trouble?

    Translation tools collect texts by scanning the code. A literal first argument is findable; a variable is not, so the string never reaches translators.

Summary

  • Every translation call names a domain; module domains look like Modules.Mymodule.Admin or Modules.Mymodule.Shop, and core domains such as Admin.Actions should be reused where they fit.
  • Use $this->trans() in PHP, {l s='' d=''} in Smarty and the trans filter in Twig, always with a literal English source text and %placeholder% values.
  • Lookup falls back from merchant edits to catalog files to the English source.
  • Content entered by merchants is stored per language: arrays keyed by language id in Configuration, and lang fields in ObjectModel.
  • Format prices with the current locale and keep amounts numeric until the last moment.

Next: Security in Modules