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

    6.1.2 • Public • Published

    Element Framework Phrasebook

    Phrasebook is a collection of APIs to define translations. In addition, the package provides locales for all core Element Framework components. The phrasebook is primarily designed to be used with @refinitiv-ui/i18n and @refinitiv-ui/translate packages.

    Phrasebook

    Phrasebook is a singleton that contains all translations. The developer can get a translation or observe translation changes.

    Define new translation

    All translations are defined per locale and scope. locale can be a top level locale (for instance en, ru, zn) or a region locale (for instance en-GB, uz-Cyrl-UZ). scope is usually an element name. If the scope is not defined, the translations are considered as default and are accessible for every scope.

    To define a default locale:

    Phrasebook.define('en', { OK: 'OK' });
    Phrasebook.define('ru', { OK: 'Хорошо' });

    To define a scoped locale:

    Phrasebook.define('en', 'ef-element', { TEST_ELEMENT: 'Test Element' });
    Phrasebook.define('ru', 'ef-element', {
      TEST_ELEMENT: 'Элемент для тестирования',
    });

    You can get translations by calling get method. The response always includes scoped translations combined with default translations.

    // Get scoped translations. Outputs: { OK: 'OK', TEST_ELEMENT: 'Test Element' }
    console.log(Phrasebook.get('en', 'ef-element'));
    
    // Get default translations. Outputs: { OK: 'OK' }
    console.log(Phrasebook.get('en'));
    console.log(Phrasebook.get('en', 'unknown-element'));

    You can get the list of supported locales for the scope by calling supported method:

    // Outputs: ['en', 'ru']
    console.log(Phrasebook.supported('ef-element'));
    
    // Outputs: []
    console.log(Phrasebook.supported('unknown-element'));

    Observe Phrasebook

    The main benefit of using Phrasebook is the ability to observe changes in translations. As soon as the translation changes or the new translation defined the callback function is called. This allows dynamic loading of translations (e.g. from CDN).

    To observer translations:

    // Observe requires a unique key. Usually it is an HTML element, but can be any object, like Symbol
    const element = document.createElement('ef-element');
    Phrasebook.observe(element, 'ef-element', (locale) => {
      console.log(locale);
    });
    
    // Outputs: 'en'.
    Phrasebook.define('en', 'ef-element', { TEST_ELEMENT: 'Test Element' });
    
    // Publishing default calls callback as well. Outputs: 'ru'.
    Phrasebook.define('ru', { OK: 'Хорошо' });

    To stop observing translation use disconnect method. This is usually required when the element is removed from DOM tree.

    Phrasebook.disconnect(element);

    Core Element Translations

    The package is deployed with all translations required by Element Framework components.

    Structure

    Define locales inside src\locale. The following structure must be followed:

    locale/
    |--[locale]/
    |     |--[component-name].ts
    |     |--shared.ts
    

    You must ensure that all keys are populated for every locale.

    Format

    The key is the reference with which to return the translation value.

    Each translation value is in the ICU format. A simpler formatting guide can be found at messageformat, or for an online checker: Translate ICU messages.

    import { Phrasebook } from '../../';
    import './shared';
    
    const translations = {
      KEY_TO_USE:
        'Du hast {numPhotos, plural, =0 {keine Bilder.} =1 {ein Bild.} other {# Bilder.}}',
    };
    
    Phrasebook.define('de', 'emerald-color-dialog', translations);
    
    export default translations;

    Keywords

    none

    Install

    npm i @refinitiv-ui/phrasebook

    DownloadsWeekly Downloads

    296

    Version

    6.1.2

    License

    Apache-2.0

    Unpacked Size

    111 kB

    Total Files

    181

    Last publish

    Collaborators

    • ef-ci