===========
Translation
===========

.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>

ownCloud's translation system is powered by `Transifex <https://www.transifex.com/projects/p/owncloud/>`_. To start translating sign up and enter a group. If your community app should be added to Transifex contact one of the `core developers <https://owncloud.org/contact/>`_ to set it up for you.

PHP
===
Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor


.. code-block:: php

    <?php
    namespace OCA\MyApp\AppInfo;

    use \OCP\AppFramework\App;

    use \OCA\MyApp\Service\AuthorService;


    class Application extends App {

        public function __construct(array $urlParams=array()){
            parent::__construct('myapp', $urlParams);

            $container = $this->getContainer();

            /**
             * Controllers
             */
            $container->registerService('AuthorService', function($c) {
                return new AuthorService(
                    $c->query('L10N')
                );
            });

            $container->registerService('L10N', function($c) {
                return $c->query('ServerContainer')->getL10N($c->query('AppName'));
            });
        }
    }

Strings can then be translated in the following way:

.. code-block:: php

    <?php
    namespace OCA\MyApp\Service;

    use \OCP\IL10N;


    class AuthorService {

        private $trans;

        public function __construct(IL10N $trans){
            $this->trans = $trans;
        }

        public function getLanguageCode() {
            return $this->trans->getLanguageCode();
        }

        public sayHello() {
            return $this->trans->t('Hello');
        }

        public function getAuthorName($name) {
            return $this->trans->t('Getting author %s', array($name));
        }

        public function getAuthors($count, $city) {
            return $this->trans->n(
                '%n author is currently in the city %s',  // singular string
                '%n authors are currently in the city %s',  // plural string
                $count,
                array($city)
            );
        }
    }



Templates
=========
In every template the global variable **$l** can be used to translate the strings using its methods **t()** and **n()**:

.. code-block:: php

    <div><?php p($l->t('Showing %s files', $_['count'])); ?></div>

    <button><?php p($l->t('Hide')); ?></button>

JavaScript
==========
There is a global function **t()** available for translating strings. The first argument is your app name, the second argument is the string to translate.

.. code-block:: js

    t('myapp', 'Hello World!');

For advanced usage, refer to the source code **core/js/l10n.js**, **t()** is bind to **OC.L10N.translate()**.

Hints
=====
In case some translation strings may be translated wrongly because they have multiple meanings, you can add hints which will be shown in the Transifex web-interface:

.. code-block:: php

    <ul id="translations">
        <li id="add-new">
            <?php
                // TRANSLATORS Will be shown inside a popup and asks the user to add a new file
                p($l->t('Add new file')); 
            ?>
        </li>
    </ul>

Creating your own translatable files
====================================

If Transifex is not the right choice or the app is not accepted for translation,
generate the gettext strings by yourself by creating an :file:`l10n/` directory
in the app folder and executing::


    cd /srv/http/owncloud/apps/myapp/l10n
    perl l10n.pl read myapp

The translation script requires **Locale::PO** and **gettext**, installable via::

    apt-get install liblocale-po-perl gettext

The above script generates a template that can be used to translate all strings
of an app. This template is located in the folder :file:`template/` with the
name :file:`myapp.pot`. It can be used by your favored translation tool which
then creates a :file:`.po` file. The :file:`.po` file needs to be placed in a
folder named like the language code with the app name as filename - for example
:file:`l10n/es/myapp.po`. After this step the perl script needs to be invoked to
transfer the po file into our own fileformat that is more easily readable by
the server code::

    perl l10n.pl write myapp

Now the following folder structure is available::

    myapp/l10n
    |-- es
    |   |-- myapp.po
    |-- es.js
    |-- es.json
    |-- es.php
    |-- l10n.pl
    |-- templates
        |-- myapp.pot

You then just need the :file:`.php`, :file:`.json` and :file:`.js` files for a
working localized app.
