Neolithic Programming Machine

    @refinitiv-ui/i18n
    TypeScript icon, indicating that this package has built-in type declarations

    6.0.3 • Public • Published

    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:

    Keywords

    none

    Install

    npm i @refinitiv-ui/i18n

    DownloadsWeekly Downloads

    71

    Version

    6.0.3

    License

    Apache-2.0

    Unpacked Size

    77 kB

    Total Files

    17

    Last publish

    Collaborators

    • ef-ci