Skip to main content
Version: 4.x.x

Hello World App

Tolgee can be used in any web application. It is completely framework independent. There are prepared packages for React and Angular. But first of all, let's look on simple application without any framework.

Check out our example application on github

info

Tolgee doesn't work properly when the app is opened as .html file from filesystem. Use some tool like serve npm package or Live Server VS code plugin.

Let's start with simple html code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello world</title>
  </head>
  <body>
    <h1>Hello world!</h1>
  </body>
</html>

There is text Hello world! in the body, which we would like to translate.

Loading Tolgee in your web application is as simple as including one dependency. To do so, we can simply use unpkg cdn:

<script src="https://unpkg.com/@tolgee/core/dist/tolgee.umd.min.js"></script>

To translate your content interactively, you will need one more dependency.

<script src="https://unpkg.com/@tolgee/ui/dist/tolgee-ui.umd.min.js"></script>

This dependency is Tolgee's UI, so dialog can appear when you ALT + click your translation.

Now it's time to configure the library. To do so, just pass configuration object as first parameter of Tolgee constructor.

info

Initialization has changed in version 3

<script>
  const { Tolgee, IcuFormatter } = window['@tolgee/core'];
  const tg = Tolgee.use(IcuFormatter).init({
    apiUrl: 'https://app.tolgee.io',
    apiKey: 'you_secret_api_key',
    inputPrefix: '{{',
    inputSuffix: '}}',
    watch: true,
    ui: window['@tolgee/ui'].UI,
  });
</script>

You can specify many other parameters in the configuration object, but in this example we stick with:

  • apiUrl - url of the api, where we are saving the data
  • apiKey - which you can obtain in the app or in your self-hosted app by following this documentation page
  • inputPrefix - character sequence which appears before the text you wish to translate
  • inputSuffix - character sequence which appears after the text you wish to translate
  • watch - parameter defining whether Tolgee should watch for changes in the DOM and update translations
  • ui - constructor of Tolgee's UI to render interactive translation modal window

Replace the text with the localization placeholder, wrapped with the inputPrefix and inputSuffix:

<body>
  <h1>{{hello_world}}</h1>
</body>

Finally, lets run the beast!

tg.run().then(() => {});

You should end up with this HTML document:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Hello world</title>
  </head>
  <body>
    <h1>{{hello_world}}</h1>
  </body>
  <script src="https://unpkg.com/@tolgee/core/dist/tolgee.umd.min.js"></script>
  <script src="https://unpkg.com/@tolgee/ui/dist/tolgee-ui.umd.min.js"></script>
  <script>
    const { Tolgee, IcuFormatter } = window['@tolgee/core'];
    const tg = Tolgee.use(IcuFormatter).init({
      apiUrl: 'https://app.tolgee.io',
      apiKey: 'you_secret_api_key',
      inputPrefix: '{{',
      inputSuffix: '}}',
      watch: true,
      ui: window['@tolgee/ui'].UI,
    });
    tg.run().then(() => {
      // This block is executed after tolgee loads it's translation.
      // So here you have nice possibility to remove your loading overlay
    });
  </script>
</html>

After opening this document in a browser you should be able to ALT + click your text and translate it directly. After that you should see your translated version right away!