Using with Dart

info

This integration is meant to be used just in a browser. It will not work with other Dart platforms.

To get full image of working PHP integration check our Dart example application.

To install Tolgee Dart integration, add tolgee dependency into your pubspec.yaml file.

dev_dependencies:
...
tolgee: ^1.0.0

Then run:

pub get

to get the dependency.

Dart integration library is just a wrapper for Tolgee javascript libraries, so you will also need to append these script tags into your HTML document:

<head>
...
<script src="https://unpkg.com/@tolgee/[email protected]/dist/tolgee.window.js"></script>
<script src="https://unpkg.com/@tolgee/[email protected]/dist/tolgee.window.js"></script>
<script defer src="main.dart.js"></script> <!-- here goes your dart main... -->
</head>

Then you can use Tolgee Dart library in your code. To configure it, create configuration map:

var config = {
'apiKey': "your api key goes here",
'apiUrl': "https://app.tolgee.io",
'targetElement': window.document
.getElementsByTagName('body')
.first
};

The configuration property names are the same as in Tolgee JS Core library. See configuration.

When you got your configuration map, you can create Tolgee class instance and run it.

var tolgee = Tolgee(config);
await tolgee.run();

Translating#

The translate and instant functions are similar as in JS integration library.

To translate a string asynchronously, use translate function:

querySelector('#output').text = await tolgee.translate('hello_world');

To translate synchronously use instant function:

querySelector('#output').text = tolgee.instant('hello_world');
warning

This function behaves differently in development and production mode. Use this function just when you are sure, that your translations are loaded.

Translating with parameters#

To pass parameters, use second parameter of instant or translate functions.

querySelector('#output').text = await tolgee.translate('peter_has_n_dogs', {"dogCount": 5});

Disabling wrapping in development mode#

In rare cases the wrapping and unwrapping process can be unwanted. For example tooltips could be rendered with improper size, or you will see encoded text such as %-%:tolgee:something%-%. To avoid this, you will need to disable wrapping, which disables the in-context localization, so it will be impossible to translate the text by simple ALT + clicking it.

To do that, set the third parameter of translation functions to true

await tolgee.translate('peter_has_n_dogs', {"dogCount": 5}, true) // Peter has 5 dogs

This will return translated text directly without wrapping even in development mode.

Getting JavaScript Tolgee instance#

To get javascript Tolgee class instance, call:

var jsInstance = tolgee.getJsInstance();

Message format#

All Tolgee integrations follow ICU message format standard.

{dogsCount, plural, one {One dog is} other {# dogs are}} here.

To read more about it, check ICU Message Format documentation page.

All Tolgee JS integrations are using MessageFormat class of formatJs library.