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
i18n.text
Translates translation string into a localized text.
Syntax
i18n.text(key, [options])
Arguments
key (string): Translation string key (e.g.myExtension.welcomeMessage).options (Object): Optional parameters dictionary.
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
Translates amount into a localized price.
Syntax
i18n.price(amount, currency, fractions)
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
// 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
Translates an unix epoch (in milliseconds) to a localized date format.
Syntax
i18n.date(timestamp, [format='medium'])
Arguments
timestamp (number): Unix epoch in milliseconds (e.g. Date.now())format (string): Date format. Possible values same as in native DateTimeFormat
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
Translates an unix epoch (in milliseconds) to a localized time format.
Syntax
i18n.time(timestamp, [format='medium']
Arguments
timestamp (number): Unix epoch in milliseconds (e.g. Date.now())format (string): Date format. Possible values same as in native DateTimeFormat
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
Translates a number into a localized string.
Syntax
i18n.number(value, [fractions=0])
Arguments
value (number): A number that is being translated.fractions (number): Number of fraction digits to use.
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
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
Since the app bootstrap process happens before everything else in Shopgate Engage, you must remember that i18n methods MUST
NOT be 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);
});