Using with PHP

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

info

To use PHP integration library in development mode for in-context translating, don't forget to integrate JS library.

To install Tolgee PHP integration run:

Composer library installation#

composer require tolgee

Tolgee instance initialization#

To use Tolgee with PHP, start with creating TolgeeConfig class instance and Tolgee class instance.

<?php

use Tolgee\Core\Enums\Modes;
use Tolgee\Core\Tolgee;
use Tolgee\Core\TolgeeConfig;

$config = new TolgeeConfig();
$config->apiKey = "your api key"
$config->apiUrl = "your api url"
$config->mode = Modes::DEVELOPMENT;

$tolgee = new Tolgee($config);

Then you can simply use Tolgee to translate strings:

$tolgee->translate("hello_world");

In development mode this function will return %-%tolgee:hello_world%-%. This output is meant to be translated in browser by tolgee JS library. See hello world example.

Providing values#

You can provide translation values as second parameter of translate function.

$tolgee->translate("peter_has_n_dogs", ["dogCount" => "5"]); //

When the translation text before parameter interpolation is "Peter has {dogCount}", returned value will be

`%-%tolgee:peter_has_n_dogs:dogCount:5%-%`

Again, this value will be handled by JS library running in browser, so the visible output will be:

Peter has 5 dogs.

Message format#

info

Since v1.2-BETA, ICU message format is used.

All Tolgee integration libraries follow ICU message format. Tolgee for PHP is using MessageFormatter::format method to format the messages. That's why you will need to enable PHP intl extension.

To learn more about this format, read this article on Wikipedia. Or use play with it using this nice tool.

Safe translating#

If the translation cannot be handled by mutation observer running in browser, use third parameter noWrap = true to ge translation right away.

$tolgee->translate("peter_has_n_dogs", ["dogCount" => "5"], true); //Peter has 5 dogs.

Return value of this function is Peter has 5 dogs. This is useful when you want to use Tolgee for translations ending up in e-mails (where obviously JS library has no power) or when you can see some ugly encoded string such as %-%tolgee:peter_has_n_dogs:dogCount:5%-% in web page rendered in browser.

Production mode#

In production mode all your translations are loaded from local JSON localization files. You can obtain there files by exporting them using Tolgee Web Application.

To configure an absolute path where Tolgee will find the localization files set localFilesAbsolutePath of TolgeeConfig class instance.

$config = new TolgeeConfig();
$config->mode = Modes::PRODUCTION;
$config->localFilesAbsolutePath = __DIR__ . "/i18n/";

Importing JS library in your HTML document#

info

Running Tolgee JS package in the browser is required to translate texts in development mode. Without configuring and running Tolgee in the browser, you will get just ugly encoded strings such as

%-%tolgee:oh_no%-%

See getTolgeeFrontendPart function of our example.

<div id="loading" style="position: fixed; top:0; left: 0; width: 100%; height: 100%;
            background-color: white; display: flex; align-items: center; justify-content: center;">
    Loading...
</div>
<script src="node_modules/@tolgee/core/dist/tolgee.window.js"></script>
<script src="node_modules/@tolgee/ui/dist/tolgee.window.js"></script>
<script>
    const tg = new window["@tolgee/core"].Tolgee({
        apiUrl: "' . $this->getConfig()->apiUrl . '",
        apiKey: "' . $this->getConfig()->apiKey . '",
        defaultLanguage: "' . $this->getConfig()->defaultLanguage . '",
        inputPrefix:  "' . $this->getConfig()->inputPrefix . '",
        inputSuffix:  "' . $this->getConfig()->inputSuffix . '",
        ui: window["@tolgee/ui"].UI,
    });

    tg.lang = "' . $_GET["lang"] . '"
    tg.run().then(() => {
        document.getElementById("loading").style.display = "none";
    })
</script>

This is probably not the way you will integrate Tolgee JS libraries in your PHP application. You are probably using some PHP framework using some kind of templating engine such as Latte or Blade, but for illustration this example should be fine.

The important thing is to keep configuration parameters same as in your PHP code.

Configuration properties#

The TolgeeConfig file contains following configuration properties:

mode#

Whether to use Tolgee in development or production mode. (bool, default: Modes::PRODUCTION)

inputPrefix#

The prefix, which is prepended to encoded localization string. (string, default: %-%tolgee:)

inputSuffix#

The suffix, which is appended to encoded localization string. (string, default: %-%)

apiUrl#

The URL to fetch localization texts from in development mode. (string, default: https://app.tolgee.io)

apiKey#

Your secret key, which you can obtain in web application. (string, default: empty string)

defaultLanguage#

The default language. (string, default: en)

fallbackLanguage#

The language used when current text is not available in current language. (string, default: en)

developmentTranslationsSource#

Whether to use local files to translate without wrapping in development mode or to use values obtained from REST API.

Using of TranslationSources:LOCAL_FILE will be a bit faster. The translations will be not loaded from REST API in both back-end and front-end, but just in front-end (browser JS integration).

info

Using of TranslationSources:LOCAL_FILE could result in different result of translations, which are translated by JS library running on front-end and PHP library running on back-end. Use with caution.

(string, default: TranslationSources::API)

localFilesAbsolutePath#

Absolute path to directory, where exported translations are loaded from in production mode or with safe translating. (string, default: __DIR__ . "../../../../i18n")