Commerce v1 Developer Internationalisation

Commerce 1.3 introduced the ability to add internationalisation to any object type descending comSimpleObject and managed through the Commerce interface.

For basic usage instructions, see the documentation here. This documentation goes into the technical implementation and enabling multilingual fields in custom models.

Model description

Primary language strings are stored on the respective model in their normal fields, e.g. a name or description field.

Translations are stored on the comI18n model (commerce_i18n database table) with principal, principal_id, and field keys to identify what the translation is for specifically.

For example, given a product, the comI18n model for its name translations would be identifiable by:

  • principal = 'comProduct'
  • principal_id = <id of product>
  • field = 'name'`

We do not recommend interfacing with the comI18n model directly, with the exception if you're looking to programmatically add/update large batches of translations at a time. For other use cases, use the utilities provided on the object itself, described below.

Object utilities

Each object in Commerce extends comSimpleObject, which provides the following utilities to more easily interact with translations:

getTranslation(string $field, [string $lang = current language]): string

Returns either the translated value for $field in the provided (or current) language, or the primary value for the field.

If you're just looking to access a translation, note that toArray() will automatically add fields such as name_en, name_fr for enabled languages as well (which may be optimized in the query or cache, unlike getTranslation). You only need to specifically call getTranslation in specific circumstances where you have an object that wasn't primed with the translation.