@refinitiv-ui/i18n
Advanced tools
@refinitiv-ui/i18n provides wrappers and APIs around formatjs IntlMessageFormat and @refinitiv-ui/phrasebook. In addition, it provides tools to observe lang attribute changes.
Use with @refinitiv-ui/translate to translate Element Framework components.
@refinitiv-ui/i18n provides a set of APIs to facilities translations.
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');
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);
@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');
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"
@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:
Creating instances of Intl formats is an expensive operation. @refinitiv-ui/i18n re-uses Intl Format Cache to memoise translations.
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.
You can get additional information about internationalization:
FAQs
i18n support for Web Components
The npm package @refinitiv-ui/i18n receives a total of 246 weekly downloads. As such, @refinitiv-ui/i18n popularity was classified as not popular.
We found that @refinitiv-ui/i18n demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.