218 lines
7.2 KiB
Markdown
218 lines
7.2 KiB
Markdown
# Introduction <a id="module-translation-introduction"></a>
|
|
|
|
Icinga Web 2 provides localization out of the box - for the core application and the modules, that means
|
|
that you can with a lightness use existent localizations, update or even create you own localizations.
|
|
|
|
The chapters [Translation for Developers](03-Translation.md#module-translation-developers),
|
|
[Translation for Translators](03-Translation.md#module-translation-translators) and
|
|
[Testing Translations](03-Translation.md#module-translation-tests) will introduce and explain you, how to take
|
|
part on localizing Icinga Web 2 for different languages and how to use the
|
|
`translation module` to make your life much easier.
|
|
|
|
## Translation for Developers <a id="module-translation-developers"></a>
|
|
|
|
To make use of the built-in translations in your applications code or views, you should use the method
|
|
`$this->translate('String to be translated')`, let's have a look at an example:
|
|
|
|
```php
|
|
<?php
|
|
|
|
class ExampleController extends Controller
|
|
{
|
|
public function indexAction()
|
|
{
|
|
$this->view->title = $this->translate('Hello World');
|
|
}
|
|
}
|
|
```
|
|
|
|
So if there a translation available for the `Hello World` string you will get an translated output, depends on the
|
|
language which is set in your configuration as the default language, if it is `de_DE` the output would be
|
|
`Hallo Welt`.
|
|
|
|
The same works also for views:
|
|
|
|
```
|
|
<h1><?= $this->title ?></h1>
|
|
<p>
|
|
<?= $this->translate('Hello World') ?>
|
|
<?= $this->translate('String to be translated') ?>
|
|
</p>
|
|
```
|
|
|
|
If you need to provide placeholders in your messages, you should wrap the `$this->translate()` with `sprintf()` for e.g.
|
|
sprintf($this->translate('Hello User: (%s)'), $user->getName())
|
|
|
|
### Translating plural forms <a id="module-translation-plural-forms"></a>
|
|
|
|
To provide a plural translation, just use the `translatePlural()` function.
|
|
|
|
```php
|
|
<?php
|
|
|
|
class ExampleController extends Controller
|
|
{
|
|
public function indexAction()
|
|
{
|
|
$this->view->message = $this->translatePlural('Service', 'Services', 3);
|
|
}
|
|
}
|
|
```
|
|
|
|
### Context based translation <a id="module-translation-context-based"></a>
|
|
|
|
If you want to provide context based translations, you can easily do it with an extra parameter in both methods
|
|
`translate()` and `translatePlural()`.
|
|
|
|
```php
|
|
<?php
|
|
|
|
class ExampleController extends Controller
|
|
{
|
|
public function indexAction()
|
|
{
|
|
$this->view->title = $this->translate('My Titile', 'mycontext');
|
|
$this->view->message = $this->translatePlural('Service', 'Services', 3, 'mycontext');
|
|
}
|
|
}
|
|
```
|
|
|
|
## Translation for Translators <a id="module-translation-translators"></a>
|
|
|
|
Icinga Web 2 internally uses the UNIX standard gettext tool to perform internationalization, this means translation
|
|
files in the .po file format are supplied for text strings used in the code.
|
|
|
|
There are a lot of tools and techniques to work with .po localization files, you can choose what ever you prefer. We
|
|
won't let you alone on your first steps and therefore we'll introduce you a nice tool, called Poedit.
|
|
|
|
### Poedit <a id="module-translation-translators-poedit"></a>
|
|
|
|
First of all, you have to download and install [Poedit](http://poedit.net).
|
|
When you are done, you have to configure Poedit.
|
|
|
|
#### Configuration <a id="module-translation-translators-poedit-configuration"></a>
|
|
|
|
`Personalize`: Please provide your Name and E-Mail under Identity.
|
|
|
|
|
|
|
|
`Editor`: Under the `Behavior` the Automatically compile .mo files on save, should be disabled.
|
|
|
|
|
|
|
|
`Translations Memory`: Under the `Database` please add your languages, for which are you writing translations.
|
|
|
|
|
|
|
|
When you are done, just save your new settings.
|
|
|
|
#### Editing .po files <a id="module-translation-translators-poedit-edit-po-files"></a>
|
|
|
|
To work with Icinga Web 2 .po files, you can open for e.g. the German icinga.po file which is located under
|
|
`application/locale/de_DE/LC_MESSAGES/icinga.po`, as shown below, you will get then a full list of all available
|
|
translation strings for the core application. Each module names its translation files `%module_name%.po`. For a
|
|
module called `yourmodule` the .po translation file will be named `yourmodule.po`.
|
|
|
|
|
|
|
|
|
|
Now you can make changes and when there is no translation available, Poedit would mark it with a blue color, as shown
|
|
below.
|
|
|
|
|
|
|
|
And when you want to test your changes, please read more about under the chapter
|
|
[Testing Translations](Testing Translations).
|
|
|
|
## Testing Translations <a id="module-translation-tests"></a>
|
|
|
|
If you want to try out your translation changes in Icinga Web 2, you can make use of the the CLI translations commands.
|
|
|
|
> **Note**:
|
|
>
|
|
> Please make sure that the gettext package is installed
|
|
|
|
To get an easier development with translations, you can activate the `translation module` which provides CLI commands,
|
|
after that you would be able to refresh and compile your .po files.
|
|
|
|
|
|
> **Note**
|
|
>
|
|
> The ll_CC stands for ll=language and CC=country code for e.g `de_DE`, `fr_FR`, `ru_RU`, `it_IT` etc.
|
|
|
|
### Application <a id="module-translation-tests-application"></a>
|
|
|
|
To refresh the `icinga.po` file:
|
|
|
|
```
|
|
icingacli translation refresh icinga ll_CC
|
|
```
|
|
|
|
And to compile it:
|
|
|
|
```
|
|
icingacli translation compile icinga ll_CC
|
|
```
|
|
|
|
> **Note**
|
|
>
|
|
> After a compile you need to restart the web server to get new translations available in your application.
|
|
|
|
### Modules <a id="module-translation-tests-modules"></a>
|
|
|
|
Let's assume, we want to provide German translations for our just new created module `yourmodule`.
|
|
|
|
If we haven't yet any translations strings in our .po file or even the .po file, we can use the CLI command, to do the
|
|
job for us:
|
|
|
|
```
|
|
icingacli translation refresh module yourmodule ll_CC
|
|
```
|
|
|
|
This will go through all .php and .phtml files inside the module and a look after `$this->translate()` if there is
|
|
something to translate - if there is something and is not available in the `yourmodule.po` it will update this file
|
|
for us with new strings.
|
|
|
|
Now you can open the `yourmodule.po` and you will see something similar:
|
|
|
|
```
|
|
# Icinga Web 2 - Head for multiple monitoring backends.
|
|
# Copyright (C) 2014 Icinga Development Team
|
|
# This file is distributed under the same license as Development Module.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
|
#
|
|
msgid ""
|
|
msgstr ""
|
|
"Project-Id-Version: Development Module (0.0.1)\n"
|
|
"Report-Msgid-Bugs-To: dev@icinga.com\n"
|
|
"POT-Creation-Date: 2014-09-09 10:12+0200\n"
|
|
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
|
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
|
"Language: ll_CC\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\n"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
|
|
#: /modules/yourmodule/configuration.php:6
|
|
msgid "yourmodule"
|
|
msgstr ""
|
|
```
|
|
|
|
Great, now you can adjust the file and provide the German `msgstr` for `yourmodule`.
|
|
|
|
```
|
|
#: /modules/yourmodule/configuration.php:6
|
|
msgid "Dummy"
|
|
msgstr "Attrappe"
|
|
```
|
|
|
|
The last step is to compile the `yourmodule.po` to the `yourmodule.mo`:
|
|
|
|
```
|
|
icingacli translation compile module yourmodule ll_CC
|
|
```
|
|
|
|
At this moment, everywhere in the module where the `Dummy` should be translated, it would returns the translated
|
|
string `Attrappe`.
|