Adding upstream version 2.11.4.upstream/2.11.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 204 insertions, 0 deletions

diff --git a/modules/translation/doc/03-Translation.md b/modules/translation/doc/03-Translation.md
new file mode 100644
index 0000000..14e2e88
--- /dev/null
+++ b/modules/translation/doc/03-Translation.md
@@ -0,0 +1,204 @@
+# Introduction <a id="module-translation-introduction"></a>
+
+Icinga Web 2 provides localization out of the box - for itself and the core modules.
+This module is for third party module developers to aid them to localize their work.
+
+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 modules to different languages.
+
+## Translation for Developers <a id="module-translation-developers"></a>
+
+To make use of the built-in translations in your module's 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 Title', 'mycontext');
+        $this->view->message = $this->translatePlural('Service', 'Services', 3, 'mycontext');
+    }
+}
+```
+
+## Translation for Translators <a id="module-translation-translators"></a>
+
+> **Note**:
+>
+> If you want to translate Icinga Web 2 or any module made by Icinga, please head over to
+> [translate.icinga.com](https://translate.icinga.com) instead. We won't accept any contributions
+> in this regard other than those made there.
+
+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.
+
+![Personalize](img/poedit_001.png)
+
+`Editor`: Under the `Behavior` the Automatically compile .mo files on save, should be disabled.
+
+![Editor](img/poedit_002.png)
+
+`Translations Memory`: Under the `Database` please add your languages, for which are you writing translations.
+
+![Translations Memory](img/poedit_003.png)
+
+When you are done, just save your new settings.
+
+#### Editing .po files <a id="module-translation-translators-poedit-edit-po-files"></a>
+
+> **Note**
+>
+> ll_CC stands for ll=language and CC=country code for e.g `de_DE`, `fr_FR`, `ru_RU`, `it_IT` etc.
+
+To work with .po files, open or create the one for your language located under
+`application/locale/ll_CC/LC_MESSAGES/yourmodule.po`. As shown below, you will
+get then a full list of all available translation strings for the module. Each
+module names its translation files `%module_name%.po`.
+
+![Full list of strings](img/poedit_004.png)
+
+Now you can make changes and when there is no translation available, Poedit would mark it with a blue color, as shown
+below.
+
+![Untranslated strings](img/poedit_005.png)
+
+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 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.
+
+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 de_DE
+```
+
+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 `application/locale/de_DE/LC_MESSAGES/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 de_DE
+```
+
+> **Note**
+>
+> After compiling it you need to restart the web server to get new translations available in your module.
+
+At this moment, everywhere in the module where the `Dummy` should be translated, it would return the translated
+string `Attrappe`.