i18n helper
The i18n helper is a pure javascript implementation of our translation system. Because it is not a React component, you can use it almost anywhere.
If you have not read how the translation system works in Shopgate Engage, please read the guide for Using Translation System first.
Methods
Section titled “Methods”i18n.text
Section titled “i18n.text”Translates translation string into a localized text.
Syntax
Section titled “Syntax”i18n.text(key, [options])
Arguments
Section titled “Arguments”key (string): Translation string key (e.g.myExtension.welcomeMessage).options (Object): Optional parameters dictionary.
Example
Section titled “Example”// Dictionary: { myExtension: { welcomeMessage: 'Hello {userName}' } }import { i18n } from '@shopgate/engage/core';
console.log(i18n.text('myExtension.welcomeMessage', { userName: 'John'}));// Will output 'Hello John'i18n.price
Section titled “i18n.price”Translates amount into a localized price.
Syntax
Section titled “Syntax”i18n.price(amount, currency, fractions)
Arguments
Section titled “Arguments”amount (number): Amount ($100.50 === 100.5).currency (string): Currency code (e.g.USD).fractions (boolean): Whether to always show fraction digits (100 => $100.00).
Example
Section titled “Example”// Dictionary: { myExtension: { welcomeMessage: 'Hello {userName}' } }import { i18n } from '@shopgate/engage/core';
console.log(i18n.price(100.5, 'USD', true));// Will output '$100.50'i18n.date
Section titled “i18n.date”Translates an unix epoch (in milliseconds) to a localized date format.
Syntax
Section titled “Syntax”i18n.date(timestamp, [format='medium'])
Arguments
Section titled “Arguments”timestamp (number): Unix epoch in milliseconds (e.g. Date.now())format (string): Date format. Possible values same as in native DateTimeFormat
Example
Section titled “Example”// Dictionary: { myExtension: { welcomeMessage: 'Hello {userName}' } }import { i18n } from '@shopgate/engage/core';
console.log(i18n.date(new Date(0), 'long'));// Will output 'January 1, 1970'i18n.time
Section titled “i18n.time”Translates an unix epoch (in milliseconds) to a localized time format.
Syntax
Section titled “Syntax”i18n.time(timestamp, [format='medium']
Arguments
Section titled “Arguments”timestamp (number): Unix epoch in milliseconds (e.g. Date.now())format (string): Date format. Possible values same as in native DateTimeFormat
Example
Section titled “Example”// Dictionary: { myExtension: { welcomeMessage: 'Hello {userName}' } }import { i18n } from '@shopgate/engage/core';
console.log(i18n.time(new Date(0), 'long'));// Will output '1:00:00 AM GMT+1'i18n.number
Section titled “i18n.number”Translates a number into a localized string.
Syntax
Section titled “Syntax”i18n.number(value, [fractions=0])
Arguments
Section titled “Arguments”value (number): A number that is being translated.fractions (number): Number of fraction digits to use.
Example
Section titled “Example”// Dictionary: { myExtension: { welcomeMessage: 'Hello {userName}' } }import { i18n } from '@shopgate/engage/core';
console.log(i18n.number(100, 2));// Will output '100.00'i18n helper bootstrap
Section titled “i18n helper bootstrap”Please note that the i18n helper is a singleton, meaning that whenever you import this module, it always returns the same i18n object.
The i18n object is being initialised during the app bootstrap process when the dictionary is being prepared and passed to the i18n object.
Once the dictionary is passed, the i18n helper is ready for translations.
If you call the i18n translation methods before, an error logs in the console and returns nothing.
How to avoid premature use
Section titled “How to avoid premature use”Since the app bootstrap process happens before everything else in Shopgate Engage, you must remember that i18n methods MUST NOT be used in the main scope of your module. i18n MUST be used within a closure.
For the example use case, we take a subscription from How to Use Streams and Subscriptions guide.
import { loginSuccess$ } from 'MyExtensionPath/stream.js';
subscribe(loginSuccess$, ({ dispatch }) => { // Perform tasks after the user has logged in.});Let’s say we want to show the translated message “Welcome to my Shop” as a javascript alert after the user logs in.
import { i18n } from '@shopgate/engage/core'import { loginSuccess$ } from 'MyExtensionPath/stream.js';
const message = i18n.text('myextension.welcomeMessage');
subscribe(loginSuccess$, ({ dispatch }) => { // Perform tasks after the user has logged in. alert(message);});In the above example, the const message = i18n.text('myextension.welcomeMessage'); line is executed at the same time that the entire file is being imported.
This might happen before i18n is ready.
To fix this code, we just need to move the message generation into the subscription callback.
import { i18n } from '@shopgate/engage/core'import { loginSuccess$ } from 'MyExtensionPath/stream.js';
subscribe(loginSuccess$, ({ dispatch }) => { // Perform tasks after the user has logged in. const message = i18n.text('myextension.welcomeMessage'); alert(message);});