Wrapping and observing

Invisible wrapping (default)

Tolgee offers unique technology for in-context translating, it combines simplicity of regular i18n libraries with comfort of in-context translating directly in your app.

How it works? Try to run tolgee in development mode:

import { Tolgee, DevTools } from '@tolgee/web';

const tolgee = Tolgee().use(DevTools()).init({
  language: 'en',
  apiUrl: 'https://app.tolgee.io',
  apiKey: '<your project API key>',
});

tolgee.run();

console.log(Array.from(tolgee.t('test')));

You should see translation individual characters that were produced by t function.

// [... translation value ... , "", "", "", "", "", "", "", "", ""]

What are these empty characters at the end? They are not actually empty, only zero width, so they are not visible.

Tolgee passes secret information into each translation, which is then detectable in the dom. We use MutationObserver to check all dom changes and search for these secret characters, to find the exact locations of translations. This method is very reliable and brings basically no overhead on the developer side. You can read more in this blog post.

We call this mechanism wrapping. You can check the information, which is included with the translation by calling tolgee.unwrap method, which will give you the information about the translation.

Why this solution?

We wanted something which is almost invisible to the developer, but reliable and doesn't break your app.

Because we actually return the translation that should be rendered only with some extra characters, you can use any custom formatter (even outside Tolgee) and modify the string. The secret information will stay intact as it's a valid part of the string.

Text wrapping

There is also a more straightforward solution which is called text observer, which uses plain text for encoding the key info and can be more practical in some cases.

info

Wrapping is part of ObserverPlugin, which is included in DevTools.