Language Variables¶

PO Files¶

The translations of CS-Cart, Multi-Vendor, or any add-on are stored in PO files (portable object). Each language must have a separate PO file that stores the values of the language variables.

PO is a widely used format: many services related to localization can import and export PO files. For example, we use Crowdin to translate CS-Cart.

PO files are located in the subfolders of var/langs of your CS-Cart/Multi-Vendor installation. You can edit them with special programs or a simple text editor.

Structure of a Language Variable¶

This is what a language variable in the PO file for the English language looks like:

msgctxt "Languages::email_marketing.subscription_confirmed"
msgid "Thank you for subscribing to our newsletter"
msgstr "Thank you for subscribing to our newsletter"

And here’s the same language variable in the French PO file:

msgctxt "Languages::email_marketing.subscription_confirmed"
msgid "Thank you for subscribing to our newsletter"
msgstr "Merci de votre inscription à notre newsletter"

• msgctxt—the message context that serves to identify the same lines of text in different parts of the program. In CS-Cart, Multi-Vendor, and their add-ons we use message context to store the name of the language variable as it appears in the Smarty templates and PHP code (except for the prefixes).

  PO files store the translations of strings, add-on names and descriptions, the names of various settings and sections. That’s why translations for different types of data have different prefixes. The names of the language variables that appear in the PHP or TPL files must begin with the Languages:: prefix.

  Important

  Omit the prefixes when passing the name of the language variable to the translation function.

  The name of the language variable must be unique among the language variables that belong to the core and installed add-ons. That’s why it’s important to put the name of the add-on at the beginning of msgctxt. For example, this is a language variable of the Email Marketing add-on:

  msgctxt "Languages::email_marketing.subscription_confirmed"
  

• msgid—the value of the language variable in the original language. We recommend to specify the value in English here—it’s easier to find translators who know English.

• msgstr—the translation of the original text to the target language. In the PO file for the original language msgstr will be the same as msgid.

Placeholders¶

You may need to add changeable data to the language variables, such as product names, links, the number of elements, etc. This is done via placeholders that are put in the square brackets, for example:

msgctxt "Languages::admin_text_letter_footer"
msgid "E-shop of [company_name]."
msgstr "E-shop of [company_name]."

See how a placeholder is used in a Smarty template.

Plural Forms¶

Many languages have different singular and plural word forms. For example, let’s take two possible phrases:

• (The delivery will take) 1 day.
• (The delivery will take) 2 days.

If you create a language variable with different forms, use the | symbol to separate forms in msgid and msgstr. Also add the [n] placeholder that will be replaced with a number. Here’s the example of a language variable with two forms:

msgctxt "Languages::n_days"
msgid "[n] day|[n] days"
msgstr "[n] day|[n] days"

Some languages (for example, Russian) have multiple plural forms. If the target language has more plural forms than the original language, then:

• msgid remains the same as in the original language.
• msgstr has the description of all the forms of the target language.

Here’s the same language variable for the Russian language, that has two plural forms:

msgctxt "Languages::n_days"
msgid "[n] day|[n] days"
msgstr "[n] день|[n] дня|[n] дней"

When listing multiple word forms, the singular form always comes first. The order, in which the forms for different languages are listed, complies with the Language Plural Rules.

In PHP Code¶

The special core function called __ is used in the PHP code to show the value of a language variable:

function __($var, $params = array(), $lang_code = CART_LANGUAGE);

The only required parameter is the name of the language variable. The second parameter passes the values of placeholders, and the third parameter specifies the target language.

Here’s the example of the __ function:

$confirmed_text = __('email_marketing.subscription_confirmed');
fn_set_notification('I',$confirmed_text, $msg);

In Smarty Templates¶

You can use __ to insert a language variable into a Smarty template. Surround the expression with curly brackets. For example, this is how you insert the hello language variable:

{__("hello")}

Expressions like this are replaced with the calling of the __ method of the Smarty wrapper class during template compilation. In turn, that class calls the core function described above.

Placeholders¶

Here is a language variable with a placeholder, inserted into a template:

<p>
   {__("admin_text_letter_footer", ["[company_name]" => $settings.Company.company_name])}
</p>

Plural Forms¶

When using a language variable with multiple plural forms, pass the substituted number instead of the [n] placeholder in the second parameter of the __ function. For example:

$return[$service_code]['delivery_time'] = __("n_days", array($shipment->GuaranteedDaysToDelivery));

Depending on the passed number, an appropriate form will be selected automatically. For example, for the English language that would be:

• 0 days
• 1 day
• 3 days