Merge branch 'feature/translation-module-documentation-7113'

modules/translation/doc/translation.md

@@ -0,0 +1,165 @@
+# Introduction
+
+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](Translation for Developers),
+[Translation for Translators](Translation for Translators) and [Testing Translations](Testing Translations) 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
+
+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 setted 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())
+
+# Translation for Translators
+
+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
+
+First of all, you have to download and install Poedit from http://poedit.net, when you are done, you have to do some
+configuration under the Preferences.
+
+#### Configuration
+
+__Personalize__: Please provide your Name and E-Mail under Identity.
+
+![Personalize](/img/translation/doc/poedit_001.png)
+
+__Editor__: Under the Behavior the Automatically compile .mo files on save, should be disabled.
+
+![Editor](/img/translation/doc/poedit_002.png)
+
+__Translations Memory__: Under the Database please add your languages, for which are you writing translations.
+
+![Translations Memory](/img/translation/doc/poedit_003.png)
+
+When you are done, just save your new settings.
+
+#### Editing .po files
+
+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 it's translation files `%module_name%.po`. For a
+module called __yourmodule__ the .po translation file will be named `yourmodule.po`.
+
+
+![Full list of strings](/img/translation/doc/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/translation/doc/poedit_005.png)
+
+And when you want to test your changes, please read more about under the chapter
+[Testing Translations](Testing Translations).
+
+# Testing Translations
+
+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
+
+To refresh the __icinga.po__:
+
+    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
+
+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 development 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 updates 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.org\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 development ll_CC
+
+At this moment, everywhere in the module where the `Dummy` should be translated, it would returns the translated
+string `Attrappe`.