fluent.js
    Preparing search index...

    Class DOMLocalization

    The DOMLocalization class is responsible for fetching resources and formatting translations.

    It implements the fallback strategy in case of errors encountered during the formatting of translations and methods for observing DOM trees with a MutationObserver.

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    bundles generateBundles mutationObserver observerConfig pendingElements pendingrAF resourceIds roots windowElement

    Methods

    addResourceIds connectRoot disconnectRoot formatValue formatValues getAttributes handleEvent onChange pauseObserving removeResourceIds resumeObserving setAttributes translateElements translateFragment translateRoots

    Constructors

    Properties

    bundles: any
    generateBundles: Function
    mutationObserver: null | MutationObserver
    observerConfig: {
        attributeFilter: string[];
        attributes: boolean;
        characterData: boolean;
        childList: boolean;
        subtree: boolean;
    }
    pendingElements: Set<any>
    pendingrAF: any
    resourceIds: string[]
    roots: Set<any>
    windowElement: null | Window & typeof globalThis

    Methods

    • Add newRoot to the list of roots managed by this DOMLocalization.

      Additionally, if this DOMLocalization has an observer, start observing newRoot in order to translate mutations in it.

      Parameters

      • newRoot: Element

        Root to observe.

      Returns void

    • Remove root from the list of roots managed by this DOMLocalization.

      Additionally, if this DOMLocalization has an observer, stop observing root.

      Returns true if the root was the last one managed by this DOMLocalization.

      Parameters

      • root: Element

        Root to disconnect.

      Returns boolean

    • Retrieve the translation corresponding to the id identifier.

      If passed, args is a simple hash object with a list of variables that will be interpolated in the value of the translation.

      Returns a Promise resolving to the translation string.

      Use this sparingly for one-off messages which don't need to be retranslated when the user changes their language preferences, e.g. in notifications.

      Parameters

      • id: string

        Identifier of the translation to format

      • Optionalargs: Object

        Optional external arguments

      Returns Promise<string>

      docL10n.formatValue(
        'hello', { who: 'world' }
      ).then(console.log);

      // 'Hello, world!'

    • Retrieve translations corresponding to the passed keys.

      A generalized version of DOMLocalization.formatValue. Keys must be {id, args} objects.

      Returns a Promise resolving to an array of the translation strings.

      Parameters

      • keys: Object[]

      Returns Promise<string[]>

      docL10n.formatValues([
        {id: 'hello', args: { who: 'Mary' }},
        {id: 'hello', args: { who: 'John' }},
        {id: 'welcome'}
      ]).then(console.log);

      // ['Hello, Mary!', 'Hello, John!', 'Welcome!']

    • Get the data-l10n-* attributes from DOM elements.

      localization.getAttributes(
        document.querySelector('#welcome')
      );
      // -> { id: 'hello', args: { who: 'world' } }

      Parameters

      • element: Element

        HTML element

      Returns { args: Object; id: string }

    • This method should be called when there's a reason to believe that language negotiation or available resources changed.

      Parameters

      • eager: boolean = false

      Returns void

    • Set the data-l10n-id and data-l10n-args attributes on DOM elements. FluentDOM makes use of mutation observers to detect changes to data-l10n-* attributes and translate elements asynchronously. setAttributes is a convenience method which allows to translate DOM elements declaratively.

      You should always prefer to use data-l10n-id on elements (statically in HTML or dynamically via setAttributes) over manually retrieving translations with format. The use of attributes ensures that the elements can be retranslated when the user changes their language preferences.

      localization.setAttributes(
        document.querySelector('#welcome'), 'hello', { who: 'world' }
      );

      This will set the following attributes on the #welcome element. The MutationObserver will pick up this change and will localize the element asynchronously.

      <p id='welcome'
        data-l10n-id='hello'
        data-l10n-args='{"who": "world"}'>
      </p>

      Parameters

      • element: Element

        Element to set attributes on

      • id: string

        l10n-id string

      • args: {}

        KVP list of l10n arguments

      Returns Element

    • Translate a list of DOM elements asynchronously using this DOMLocalization object.

      Manually trigger the translation (or re-translation) of a list of elements. Use the data-l10n-id and data-l10n-args attributes to mark up the DOM with information about which translations to use.

      Returns a Promise that gets resolved once the translation is complete.

      Parameters

      • elements: Element[]

        List of elements to be translated

      Returns Promise<any>

    • Translate a DOM element or fragment asynchronously using this DOMLocalization object.

      Manually trigger the translation (or re-translation) of a DOM fragment. Use the data-l10n-id and data-l10n-args attributes to mark up the DOM with information about which translations to use.

      Returns a Promise that gets resolved once the translation is complete.

      Parameters

      • frag: DOMFragment

        Element or DocumentFragment to be translated

      Returns Promise<any>

    • Translate all roots associated with this DOMLocalization.

      Returns Promise<any>

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods