Language variables are one of the primary means for internationalization and localization of CS-Cart, Multi-Vendor, and their add-ons.
Texts in various languages don’t appear in the PHP code or Smarty template files directly—a special function is called instead. The name of the language variable is passed to the function, which then returns the text in one of the languages, depending on the user’s locale.
Declaring Language Variables
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 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:
And here’s the same language variable in the French PO file:
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
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:
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.
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:
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:
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:
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.
Using Language Variables
In PHP Code
The special core function called
__ is used in the PHP code to show the value of a language variable:
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
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:
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.
Here is a language variable with a placeholder, inserted into a template:
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:
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