Skip to main content
Version: 4.x.x

Configuration

All Tolgee JS integrations such as integration library for Angular or React share the same configuration properties.

Configuration properties​

apiUrl​

Url of Tolgee server.

apiKey​

Your api key, which can be obtained using Tolgee web application.. When both apiKey and apiUrl properties are provided, Tolgee runs in development mode, otherwise it runs in production mode.

inputPrefix and inputSuffix​

In development mode, strings to be translated are wrapped by @tolgee/core library at first and then parsed and replaced with translated value. This mechanism is called wrapping.

inputPrefix is inserted before the encoded string and inputSuffix is inserted after the string. By those 2 strings Tolgee recognises strings, which are meant to be translated, so its good idea to make them unique enough not to collide with any other strings, which can appear in DOM.

Example:

inputPrefix = '%-%tolgee:';
inputSuffix = '%-%';

These strings are unique enough to not clash with any other strings in your DOM, so it will not break your document.

defaultLanguage​

Default language to be set by as currentLanguage default. (default: en)

fallbackLanguage​

When translation is not provided in current language, Tolgee tries to find it in fallbackLanguage. (default: value of defaultLanguage property)

forceLanguage​

By default, Tolgee tries to set the language according to user's system language. Sometimes you need to force it to use specific language. For example when you are working with SSR or your language is determined by route. Providing value to forceLanguage will disable language switching and Tolgee will use just the forced language.

const config = {
  forceLanguage: 'en',
};

preloadFallback​

When true Tolgee loads both current language and fallback language before promise is resolved from Tolgee.run() method. Otherwise, Tolgee will try to load fallback language localization data just when it's needed (when some translation is missing in current language). That way some inappropriate value may be rendered when some text is missing in current language. (default false)

availableLanguages​

Tolgee chooses language automatically by user's default language provided by browser navigator object. To do so, it needs to know which languages are available to determine whether user's preferred language is supported by your app.

If user's language is not available, defaultLanguage is used instead.

Default: ['en']

enableLanguageStore​

Automatically store user language in localStorage. (default true)

enableLanguageDetection​

Use auto language detection by browser locale. (default true)

filesUrlPrefix​

In production mode, localization texts are loaded from json files, which are loaded from url prefixed with this property value.

When your current language is "en" and your filesUrlPrefix is https://example.com/loc/files/, your localization data will be loaded from file loaded from url https://example.com/loc/files/en.json.

You can obtain these files by downloading them from Tolgee Web Application

staticData​

Using this property, you can provide localization data to Tolgee as an object. Tolgee will use this data in production mode.

import * as localeEn from 'i18n/en.json';
import * as localeDe from 'i18n/de.json';

...
const config = {
  staticData: {
        en: localeEn,
        de: localeDe,
      }
  };

or you can provide the data using provider functions returning promises, so it works great with dynamic import feature:

const config = {
  staticData: {
    en: () => import('./i18n/en.json'),
    de: () => import('./i18n/de.json'),
  },
};

watch​

In development mode, watch is always set to true because Tolgee needs to find strings to replace with translated values every time when DOM is changed. In production mode, watching is not always necessary because integration libraries for React and Angular return translated values directly without wrapping, so wrapped encoded strings are never inserted to DOM.

If you are not using any JS framework, and you wish Tolgee to replace wrapped encoded texts even in production mode, set this to true.

watch: true is used in preparing for production part or get started tutorial, because this tutorial is framework independent and so no framework integration library is used.

ui​

To use Tolgee in development with in-context localization, you need to provide a constructor for UI class.

Example:

ui: window["@tolgee/ui"].UI,

@tolgee/core and @tolgee/ui are separated to reduce size of @tolgee/core library while ui library is needed just in development mode and may be omitted in production mode.

targetElement​

Element where wrapped strings are expected in development mode. (default: document.body)

tagAttributes​

Tolgee is able to watch also for wrapped localization strings in attributes of DOM elements. These attributes must be specified in these configuration properties.

Default:

tagAttributes: {
    textarea: ['placeholder'],
    input: ['value', 'placeholder'],
    img: ['alt'],
    '*': ['aria-label', 'title'],
}

highlightKeys​

By default, in development mode, when you move mouse over an element containing translated text and key ALT is down, this element is highlighted by changing its background color. To modify the key use highlightKeys property.

Example:

import {ModifierKey} from "../clients/js/packages/core/lib/index";

...

    highlightKeys: [ModifierKey.Shift, ModifierKey.Alt]

Default: [ModifierKey.Alt]

passToParent​

There are elements which can contain wrapped string to be translated, but user is not able to click on them. For example an option of select HTML element cannot be used for capturing click even with ALT down. For these reasons you can configure Tolgee to "pass" these strings to parent and listen for click events on the parent.

Default: ["option", "optgroup"]

restrictedElement​

Array of elements in which you don't want Tolgee to replace wrapped strings.

Default: ['script', 'style']

highlightColor​

Highlighter border color.

Default: rgb(255 0 0)  

highlightWidth​

Border width of highlighter.

Default: 5px

wrapperMode​

Will determine how are translations wrapped (read more)

  • text (default) - uses standard wrapping
  • invisible (experimental) - uses zero width invisible characters to encode key info directly into translation