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.
info
Inicialization has changed in version 3
<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 { Tolgee, IcuFormatter } = window["@tolgee/core"]
const tg = Tolgee.use(IcuFormatter).init({
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"
)