Please note: this is currently a beta release. To find out more about getting access to this integration, please contact your BRYTER Customer Success Manager or firstname.lastname@example.org.
What are multi-language modules and why would you use them?
With multi-language modules, authors can configure multiple languages using a single module structure shared across all languages.
Prior to the introduction of multi-language modules, authors who wished to create modules in multiple languages needed to either 1) build an individual module for every language option or 2) duplicate content, resulting in a large and complex module structure. Both options are prone to errors and require intense upkeep.
Authors can choose to display a module in up to 9 different languages. Even existing modules can be adjusted fairly easily to be made available in new languages.
How to use multi-language modules
There are three main steps to set up multiple languages in modules:
- Configuring languages in module Properties
- Setting the module language via URL Parameters, and
- Setting the default (and available) language in Publishing Settings.
Their objectives are all different. While ModuleProperties lets authors configure which languages they want to integrate into a module, Publishing Settings allows selecting a default language and, more importantly, the languages available to the end-user from the list of configured languages. This is useful when, e.g., the translation process is still underway. By using URL Parameters, authors create the technical foundation for end-users to select their preferred module language.
I. Configuring languages in module Properties
Authors can configure languages through accessing module Properties by selecting the
[ i ] Info button in the navigation bar.
Languages are added by selecting + Add another language and deleted by selecting the 🗑️ icon. When deleting a language the author is prompted to enter the name of the language to confirm the deletion, as deleting a language also deletes all associated contents.
There are currently 9 supported languages: English, German, French, Dutch, Italian, Chinese, Portuguese, Russian, and Spanish.
When editing a Node with a Content area, a drop-down button is displayed in the top right-hand corner, opposite of CONTENT, indicating the currently selected language. The drop-down menu allows switching between the different available languages, as configured in module Properties.
❗Note that the selected language persists when navigating to another Node, not automatically switching to the default language when selecting a different Node. Thus, you are in one language 'mode' at a time.
Missing language content is indicated in a number of ways:
- The language drop-down button displays a yellow dot.
- In the drop-down menu, a yellow dot is displayed next to the affected language.
- In the Quick Check, next to the affected Node will read 'Empty content field'.
II. Setting the module language via URL Parameters
Authors can utilize URL Parameters to enable end-users to set their preferred language for a module. When a user opens a module, the URL is scanned for a specific parameter. If this parameter is not found, the user is directed to an interface where they are prompted to select their preferred language. Once selected, the user is then redirected to the same module, only now the URL contains the necessary information to trigger the module to start.
Follow the steps below to create a multi-language module using URL Parameters:
1. At the top of your module, insert an Action Node, then select URL Parameter in the available Actions menu.
2. In the Node Name field, enter 'language'. In the Query Parameter Name field, enter out 'lang'.
3. Place a new Input Node. This Node will serve as the initial landing page, allowing the user to set a preferred language.
4. Fill in the Content field and set the different language options you would like to offer. In our example, we have provided three different options, including German, English, and French.
5. Insert a Value Node and set it to Text Block.
6. In the Content field, place a Conditional Block for every language option by selecting [+] INSERT and selecting Conditional block.
7. Enter the language abbreviations and set the Conditions to match the corresponding language by selecting the Conditional Block and selecting the ⚙️ icon.
8. On the Value Node, select + and select New Result from the drop-down menu. Then, select 🚩 RESULT next to the Node Name field and select Redirect.
9. Under Select module, choose your module from the drop-down menu.
10. Set the URL Parameters by entering the URL Parameter key and value.
The URL Parameter key refers to the URL Parameter name you have entered in the initial URL Parameter Action Node: lang.
In the URL Parameter value field, reference the prior Value Node that stores the language abbreviations.
11. Finally, create a new pathway that will direct the user to the start of the module. On the URL Parameter Action Node at the top of the module, select + and select Insert Action. We have opted for an Empty Action Node to mark the module Start. Now, select the Transition between the URL Parameter Action Node and the Input Node and select Add Condition.
Language = [Blank] will ensure that this pathway in the module is only taken when the URL does not contain the parameter 'lang'. Otherwise, the user is directed to the start of the module.
Below the Empty Action Node 'module Start' continue building your module as you would.
💡 For tips and tricks, refer to the Best Practice section below.
III. Setting the default language and selecting available languages in publishing settings
Authors can set a default language and select available languages through accessing the Publishing Settings by selecting the 🚀 Publish button in the navigation bar.
The default language specifies which language will be displayed if no language is otherwise specified (or the specified language is unavailable).
- Example: A module is published in English and German, with English set as the default language. When the module is accessed via a URL that includes the Parameter
lang=fr, the module will be displayed in the default language English, as French is not selected as available.
Available languages specify which of the configured languages are made available to end-users. This allows authors to, i.e., publish a version of a module while one translation is incomplete. Published modules can have these settings altered via the environment settings. Note that the default language must be selected.
The current version only supports localizing Content areas. Options, default values, etc. are not yet localizable. However, authors can work around the issue by creating localizable Text Value Nodes and using Referencing to bring in the appropriate values.
💡 As explained in the Limitations section, only Content areas are synced with the language drop-down and can offer language content. E.g., in an Input Node, the options remain the same across all languages. However, authors can work around this issue by utilizing Text Value Nodes and Referencing. In the example above, we have inserted Value Nodes, entered the option and its translations in the Content field, and @-referenced the corresponding Value Nodes in the Option fields of the Input Node.
💡 We recommend authors stick with common abbreviations in all matters relating to URL Parameters. Below is a list of the currently supported languages and their abbreviations: