I18N
@refinitiv-ui/i18n
provides wrappers and APIs around formatjs IntlMessageFormat and @refinitiv-ui/phrasebook
. In addition, it provides tools to observe lang
attribute changes.
Usage
Use with @refinitiv-ui/translate
to translate Element Framework components.
API Overview
@refinitiv-ui/i18n
provides a set of APIs to facilities translations.
t()
t
function is used to get the translation message from Phrasebook. Please refer to @refinitiv-ui/phrasebook
documentation on how to populate phrasebooks.
// get translation for "element-scope" scope, "en" locale, "TRANSLATE_KEY" with options
const message = await t('element-scope', 'en', 'TRANSLATE_KEY', {
option: 'value'
});
If the requested locale is not available, t
always tries to resolve the translation from the default locale (DEFAULT_LOCALE
). If translation cannot be found the requested translation key is returned:
// outputs 'TRANSLATION_KEY'
const message = await t('element-scope', 'unknown-LOCALE', 'TRANSLATION_KEY');
LangAttributeObserver
It is common that translations are applied based on lang
HTML attribute. Please see Language tag syntax to get additional information.
LangAttributeObserver
utilizes MutationObserver to run a callback when lang
attribute changes either on document level or on element level.
<!-- Define document level locale -->
<html lang="en-GB">
<body>
<!-- This paragraph uses document locale -->
<p id="first">This paragraph uses document locale</p>
<!-- Define element level locale -->
<p id="second" lang="ru">Этот параграф написан на русском.</p>
</body>
</html>
const paragraph1 = document.getElementById('first');
const paragraph2 = document.getElementById('second');
// start observing lang changes
LangAttributeObserver.observe(paragraph1, () => {
console.log('First paragraph locale changes');
});
LangAttributeObserver.observe(paragraph2, () => {
console.log('Second paragraph locale changes');
});
// Outputs: 'First paragraph locale changes'
document.documentElement.lang = 'it';
// Outputs: 'Second paragraph locale changes'
paragraph2.lang = 'es';
To stop observing lang
changes and avoid memory leaks you must disconnect an element.
LangAttributeObserver.disconnect(paragraph1);
LangAttributeObserver.disconnect(paragraph2);
clearCache() and clearCachedRecord()
@refinitiv-ui/i18n
caches translations for efficient re-use. In rare scenarios, you might need to clear the cache manually.
// Clear all cached records
clearCache();
// Clear cached record for specific scope and locale
clearCachedRecord('element-scope', 'en');
resolveLocale()
The function is used to get the most suitable locale for the scope by checking supported locales from Phrasebook.
// If supported locales for "element-scope" are "['en', 'zh-Hant', 'zh-Hans']"
resolveLocale('element-scope', 'en'); // resolved as "en"
resolveLocale('element-scope', 'en-GB'); // resolved as "en"
resolveLocale('element-scope', 'en-US'); // resolved as "en"
resolveLocale('element-scope', 'ru'); // resolved as "". No matching locales
resolveLocale('element-scope', 'zh'); // resolved as "". No matching locales
resolveLocale('element-scope', 'zh-Hant'); // resolved as "zh-Hant"
resolveLocale('element-scope', 'zh-Hant-HK'); // resolved as "zh-Hant"
Technical Details
Locale resolution
@refinitiv-ui/i18n
tries to match the best available locale or fallback to default if none is available.
For example, if the Phrasebooks defines the following locales: ['en', 'zh-Hant', 'zh-Hans']
. The list below shows how the locales will be resolved:
- en -> en
- en-GB -> en
- en-US -> en
- ru -> DEFAULT_LOCALE (en-GB) -> en
- zh -> DEFAULT_LOCALE (en-GB) -> en
- zh-Hant -> zh-Hant
- zh-Hant-HK -> zh-Hant
Caching
Creating instances of Intl
formats is an expensive operation. @refinitiv-ui/i18n
re-uses Intl Format Cache to memoise translations.
Unicode Extension
Translate object supports BCP47 unicode extensions. You can provide unicode as part of locale
or by passing unicodeExtensions
to t
function.
<!-- English locale with Islamic Calendar and 24h time format -->
<html lang="en-u-hc-h24-ca-islamic"></html>
const message = await t(
'element-scope',
'en',
'TRANSLATE_KEY',
{
option: 'value'
},
{
// English locale with Islamic Calendar and 24h time format
unicodeExtensions: {
hc: 'h24',
ca: 'islamic'
}
}
);
Note that you cannot provide more than one list of unicode extensions. Therefore, if extensions are provided via html and JavaScript, the list is merged.
References
You can get additional information about internationalization: