Translation

Introduction

ownCloud’s translation system is powered by Transifex. To start translating sign up and enter a group. If translations for your community app should be added to Transifex follow the steps described at the end of this page.

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

<?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:

<?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():

<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.

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:

<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 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:

sudo 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 template/ with the name myapp.pot. It can be used by your favored translation tool which then creates a .po file. The .po file needs to be placed in a folder named like the language code with the app name as filename - for example l10n/es/myapp.po. After this step the Perl script needs to be invoked to transfer the po file into our own file format 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 .php, .json and .js files for a working localized app.

How to automatically sync translations

  1. Create an initial Transifex config within the app repository under l10n/.tx/config:

    [main]
    host = https://www.transifex.com
    lang_map = ja_JP: ja
    
    [owncloud.APP_NAME]
    file_filter = <lang>/APP_NAME.po
    source_file = templates/APP_NAME.pot
    source_lang = en
    type = PO
  2. Give write permissions to the ownclouders user, within the ownCloud GitHub organization, just add the @owncloud/ci team with admin permissions.

  3. Create a pull request at drone, just add another list item to the matrix (the apps are sorted alphabetically).

  4. After merging the pull request the translations will already be synced, afterwards it will happen every night.