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

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

Nextcloud's translation system is powered by `Transifex <https://www.transifex.com/nextcloud/>`_. To start translating sign up and enter a group. If your community app should be translated by the `Nextcloud community on Transifex <https://www.transifex.com/nextcloud/nextcloud/dashboard/>`_ just follow the setup section below.

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>

Ignoring files from translation tool
------------------------------------

The translation tool scrapes the source code for method calls to  **t()**
or **n()** to extract the strings that should be translated. If you check
in minified JS code for example then those method names are also quite
common and could cause wrong extractions. For this reason we allow to
specify a list of files that the translation tool will not scrape for
strings. You simply need to add a file named :file:`.l10nignore` into
the root folder of your app and specify the files one per line::

    # compiled vue templates
    js/bruteforcesettings.js


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 executing our
`translation tool <https://github.com/nextcloud/docker-ci/tree/master/translations/translationtool>`_
in the app folder::


    cd /srv/http/nextcloud/apps/myapp
    translationtool.phar create-pot-files

The translation tool requires **gettext**, installable via::

    apt-get install gettext

The above tool generates a template that can be used to translate all strings
of an app. This template is located in the folder :file:`translationfiles/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:`translationfiles/es/myapp.po`. After this step the tool needs to be invoked to
transfer the po file into our own fileformat that is more easily readable by
the server code::

    translationtool.phar convert-po-files

Now the following folder structure is available::

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

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

Setup of the transifex sync
---------------------------

To setup the transifex sync within the Nextcloud community you need to add first the
transifex config to your app folder at :file:`.tx/config` (please replace **MYAPP** with your apps id)::

    [main]
    host = https://www.transifex.com
    lang_map = bg_BG: bg, cs_CZ: cs, fi_FI: fi, hu_HU: hu, nb_NO: nb, sk_SK: sk, th_TH: th, ja_JP: ja

    [nextcloud.MYAPP]
    file_filter = translationfiles/<lang>/MYAPP.po
    source_file = translationfiles/templates/MYAPP.pot
    source_lang = en
    type = PO

Then create a folder :file:`l10n` and a file :file:`l10n/.gitkeep` to create an
empty folder which later holds the translations.

Now the GitHub account `@nextcloud-bot <https://github.com/nextcloud-bot>`_ needs
to get write access to your repository. It will run every night and only push
commits to the master branch once there is an update to the translation. In general
you should enable the `protected branches feature <https://help.github.com/articles/configuring-protected-branches/>`_
at least for the master branch.

For the sync job there is a `configuration file <https://github.com/nextcloud/docker-ci/blob/master/translations/config.json>`_
available in our docker-ci repository. Adding there the repo owner and repo name
to the section named **app** via pull request is enough. Once this change is in
one member of the sysadmin team will deploy it to the sync server and the job
will then run once a day.

If you need help then just `open a ticket with the request <https://github.com/nextcloud/docker-ci/issues/new>`_
and we can also guide you through the steps.