CINXE.COM

<!DOCTYPE html> <html class="writer-html5" lang="en" data-content_root="../../"> <head> <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Translation — Nextcloud latest Developer Manual latest documentation</title> <link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" /> <link rel="stylesheet" type="text/css" href="../../_static/css/theme.css?v=e59714d7" /> <link rel="stylesheet" type="text/css" href="../../_static/copybutton.css?v=76b2166b" /> <link rel="stylesheet" type="text/css" href="../../_static/custom.css?v=bad88653" /> <link rel="stylesheet" type="text/css" href="../../_static/dark_mode_css/general.css?v=c0a7eb24" /> <link rel="stylesheet" type="text/css" href="../../_static/dark_mode_css/dark.css?v=70edf1c7" /> <script src="../../_static/jquery.js?v=5d32c60e"></script> <script src="../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script> <script src="../../_static/documentation_options.js?v=f4332903"></script> <script src="../../_static/doctools.js?v=9bcbadda"></script> <script src="../../_static/sphinx_highlight.js?v=dc90522c"></script> <script src="../../_static/clipboard.min.js?v=a7894cd8"></script> <script src="../../_static/copybutton.js?v=f281be69"></script> <script src="../../_static/dark_mode_js/default_light.js?v=c2e647ce"></script> <script src="../../_static/dark_mode_js/theme_switcher.js?v=358d3910"></script> <script src="../../_static/js/theme.js"></script> <link rel="index" title="Index" href="../../genindex.html" /> <link rel="search" title="Search" href="../../search.html" /> <link rel="next" title="Theming support" href="theming.html" /> <link rel="prev" title="CSS" href="css.html" /> </head> <body class="wy-body-for-nav"> <div class="wy-grid-for-nav"> <nav data-toggle="wy-nav-shift" class="wy-nav-side"> <div class="wy-side-scroll"> <div class="wy-side-nav-search" > <a href="../../index.html"> <img src="../../_static/logo-white.png" class="logo" alt="Logo"/> </a> <div role="search"> <form id="rtd-search-form" class="wy-form" action="../../search.html" method="get"> <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu"> <ul class="current"> <li class="toctree-l1"><a class="reference internal" href="../../prologue/index.html">Prologue</a></li> <li class="toctree-l1"><a class="reference internal" href="../../getting_started/index.html">Getting started</a></li> <li class="toctree-l1 current"><a class="reference internal" href="../index.html">Basic concepts</a><ul class="current"> <li class="toctree-l2"><a class="reference internal" href="../request_lifecycle.html">Request lifecycle</a></li> <li class="toctree-l2"><a class="reference internal" href="../routing.html">Routing</a></li> <li class="toctree-l2"><a class="reference internal" href="../dependency_injection.html">Dependency injection</a></li> <li class="toctree-l2"><a class="reference internal" href="../controllers.html">Controllers</a></li> <li class="toctree-l2"><a class="reference internal" href="../middlewares.html">Middlewares</a></li> <li class="toctree-l2"><a class="reference internal" href="../events.html">Events</a></li> <li class="toctree-l2 current"><a class="reference internal" href="index.html">Front-end</a><ul class="current"> <li class="toctree-l3"><a class="reference internal" href="templates.html">Templates</a></li> <li class="toctree-l3"><a class="reference internal" href="js.html">JavaScript</a></li> <li class="toctree-l3"><a class="reference internal" href="css.html">CSS</a></li> <li class="toctree-l3 current"><a class="current reference internal" href="#">Translation</a><ul> <li class="toctree-l4"><a class="reference internal" href="#php">PHP</a></li> <li class="toctree-l4"><a class="reference internal" href="#templates">Templates</a></li> <li class="toctree-l4"><a class="reference internal" href="#javascript">JavaScript</a></li> <li class="toctree-l4"><a class="reference internal" href="#important-notes">Important notes</a></li> <li class="toctree-l4"><a class="reference internal" href="#adding-translations">Adding translations</a></li> </ul> </li> <li class="toctree-l3"><a class="reference internal" href="theming.html">Theming support</a></li> </ul> </li> <li class="toctree-l2"><a class="reference internal" href="../backgroundjobs.html">Background jobs (Cron)</a></li> <li class="toctree-l2"><a class="reference internal" href="../caching.html">Caching</a></li> <li class="toctree-l2"><a class="reference internal" href="../logging.html">Logging</a></li> <li class="toctree-l2"><a class="reference internal" href="../setting.html">Settings</a></li> <li class="toctree-l2"><a class="reference internal" href="../storage/index.html">Storage and database</a></li> <li class="toctree-l2"><a class="reference internal" href="../public_share_template.html">Public share template</a></li> <li class="toctree-l2"><a class="reference internal" href="../testing.html">Testing</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="../../app_development/index.html">App development</a></li> <li class="toctree-l1"><a class="reference internal" href="../../server/index.html">Server development</a></li> <li class="toctree-l1"><a class="reference internal" href="../../digging_deeper/index.html">Digging deeper</a></li> <li class="toctree-l1"><a class="reference internal" href="../../app_publishing_maintenance/index.html">App publishing and maintenance</a></li> <li class="toctree-l1"><a class="reference internal" href="../../design/index.html">Interface & interaction design</a></li> <li class="toctree-l1"><a class="reference internal" href="../../html_css_design/index.html">HTML/CSS guidelines</a></li> <li class="toctree-l1"><a class="reference internal" href="../../client_apis/index.html">Clients and Client APIs</a></li> </ul> </div> </div> </nav> <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" > <a href="../../index.html">Nextcloud latest Developer Manual</a> </nav> <div class="wy-nav-content"> <div class="rst-content style-external-links"> <div role="navigation" aria-label="Page navigation"> <ul class="wy-breadcrumbs"> <li><a href="../../index.html" class="icon icon-home" aria-label="Home"></a></li> <li class="breadcrumb-item"><a href="../index.html">Basic concepts</a></li> <li class="breadcrumb-item"><a href="index.html">Front-end</a></li> <li class="breadcrumb-item active">Translation</li> <li class="wy-breadcrumbs-aside"> <a href="https://github.com/nextcloud/documentation/edit/master/developer_manual/basics/front-end/l10n.rst" class="fa fa-github"> Edit on GitHub</a> </li> </ul> <hr/> </div> <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article"> <div itemprop="articleBody"> <section id="translation"> <h1>Translation<a class="headerlink" href="#translation" title="Link to this heading"></a></h1> Nextcloud provides mechanisms for internationalization (make an application translatable) and localization (add translations for specific languages). This section provides detailed instructions for both aspects. In order to make your app translatable (internationalization), you should use Nextcloud’s methods for translating strings. They are available for both the server-side (PHP, Templates) as well as for the client-side (JavaScript). <section id="php"> <h2>PHP<a class="headerlink" href="#php" title="Link to this heading"></a></h2> If localized strings are used in the backend code, simply inject the <code class="docutils literal notranslate">\OCP\IL10N</code> class into your service via type hinting it in the constructor. You will automatically get the language object containing the translations of your app: <div class="highlight-php notranslate"><div class="highlight"><pre><?php namespace OCA\MyApp\Service; use OCP\IL10N; class AuthorService { /** @var IL10N */ private $l; public function __construct(IL10N $l) { $this->l = $l; } … } </pre></div> </div> Strings can then be translated in the following way: <div class="highlight-php notranslate"><div class="highlight"><pre><?php … class AuthorService { … public function getLanguageCode() { return $this->l->getLanguageCode(); } public sayHello() { // Simple string return $this->l->t('Hello'); } public function getAuthorName($name) { // String using a parameter return $this->l->t('Getting author %1$s', [$name]); } public function getAuthors($count, $city) { // Translation with plural return $this->l->n( '%n author is currently in the city %1$s', // singular string '%n authors are currently in the city %1$s', // plural string $count, // number to decide which plural to use [$city] // further parameters are possible ); } } </pre></div> </div> <section id="correct-plurals"> <h3>Correct plurals<a class="headerlink" href="#correct-plurals" title="Link to this heading"></a></h3> If you use a plural, you must also use the <code class="docutils literal notranslate">%n</code> placeholder. The placeholder defines the plural and the word without the number preceding is wrong. If you don’t know/have a number for your translation, e.g. because you don’t know how many items are going to be selected, just use an undefined plural. They exist in every language and have one form. They do not follow the normal plural pattern. Example: <div class="highlight-php notranslate"><div class="highlight"><pre><?php // BAD: Plural without count $title = $l->n('Import calendar', 'Import calendars', $selectionLength) // BETTER: Plural has count, but disrupting to read and unnecessary information $title = $l->n('Import %n calendar', 'Import %n calendars', $selectionLength) // BEST: Simple string with undefined plural $title = $l->t('Import calendars') </pre></div> </div> </section> <section id="language-of-other-users"> <h3>Language of other users<a class="headerlink" href="#language-of-other-users" title="Link to this heading"></a></h3> If you need to get the language of another user, e.g. to send them an email or inside a background job, there are also the <code class="docutils literal notranslate">force_language</code> and <code class="docutils literal notranslate">default_language</code> configuration options to consider. To make this easier, the <code class="docutils literal notranslate">OCP\L10N\IFactory</code> class comes with a <code class="docutils literal notranslate">getUserLanguage</code> method: <div class="highlight-php notranslate"><div class="highlight"><pre><?php use OCP\L10N\IFactory; class SendEmail { /** @var IFactory */ private $l10nFactory; public function __construct(IFactory $l10nFactory) { $this->l10nFactory = $l10nFactory; } public function send(IUser $user): void { $lang = $this->l10nFactory->getUserLanguage($user); $l = $this->l10nFactory->get('myapp', $lang); // … } </pre></div> </div> </section> </section> <section id="templates"> <h2>Templates<a class="headerlink" href="#templates" title="Link to this heading"></a></h2> In every template the global variable $l can be used to translate the strings using its methods t() and n(): <div class="highlight-php notranslate"><div class="highlight"><pre><div><?php p($l->t('Showing %$1s files', $_['count'])); ?></div> <button><?php p($l->t('Hide')); ?></button> </pre></div> </div> For the right date format use <code class="docutils literal notranslate"><?php p($l->l('date', time()));?></code>. </section> <section id="javascript"> <h2>JavaScript<a class="headerlink" href="#javascript" title="Link to this heading"></a></h2> There are global functions t() and n() available for translating strings in javascript code. They differ a bit in terms of usage compared to php: <ul class="simple"> <li>First argument is the appId e.g. <code class="docutils literal notranslate">'myapp'</code></li> <li>Placeholders (apart from the count in plurals) use single-mustache brackets with meaning-full descriptors.</li> <li>The parameter list is an object with the descriptors as key.</li> </ul> <div class="highlight-js notranslate"><div class="highlight"><pre>t('myapp', 'Hello World!'); t('myapp', '{name} is available. Get {linkstart}more information{linkend}', {name: 'Nextcloud 16', linkstart: '<a href="...">', linkend: '</a>'}); n('myapp', 'Import %n calendar into {collection}', 'Import %n calendars into {collection}', selectionLength, {collection: 'Nextcloud'}); </pre></div> </div> </section> <section id="important-notes"> <h2>Important notes<a class="headerlink" href="#important-notes" title="Link to this heading"></a></h2> Please also look through the following steps to improve your strings and make them better translatable by others <section id="improving-your-translations"> <h3>Improving your translations<a class="headerlink" href="#improving-your-translations" title="Link to this heading"></a></h3> You shall never split sentences and never concatenate two translations (e.g. “Enable” and “dark mode” can not be combined to “Enable dark mode”, because languages might have to use different cases)! Translators lose the context and they have no chance to possibly re-arrange words/parts as needed. Bad example: <div class="highlight-php notranslate"><div class="highlight"><pre><?php p($l->t('Select file from')) . ' '; ?><a href='#' id="browselink"><?php p($l->t('local filesystem'));?></a><?php p($l->t(' or ')); ?><a href='#' id="cloudlink"><?php p($l->t('cloud'));?></a> </pre></div> </div> Translators will translate: <ul class="simple"> <li>Select file from</li> <li>local filesystem</li> <li>‘ or ‘</li> <li>cloud</li> </ul> Translating these individual strings results in <code class="docutils literal notranslate">local filesystem</code> and <code class="docutils literal notranslate">cloud</code> losing case. The two white spaces surrounding <code class="docutils literal notranslate">or</code> will get lost while translating as well. For languages that have a different grammatical order it prevents the translators from reordering the sentence components. So the following code is a bit better, but suffers from another issue: <div class="highlight-php notranslate"><div class="highlight"><pre><?php p($l->t('Select file from <a href="#" id="browselink">local filesystem</a> or <a href="#" id="cloudlink">cloud</a>'));?> </pre></div> </div> In this case the translators can re-arrange as they like, but have to deal with your markup and can mess it up easily. It is better to keep the markup out of your code, so the following translation is even better: <div class="highlight-php notranslate"><div class="highlight"><pre><?php p($l->t('Select file from %slocal filesystem%s or %scloud%s', ['<a href="#" id="browselink">', '</a>', '<a href="#" id="cloudlink">', '</a>']));?> </pre></div> </div> But there is one last problem with this. In case the language has to turn things around, your code will still insert the parameters in the given order and they can not re-order them. To prevent this last hurdle simply use positioned placeholders like <code class="docutils literal notranslate">%1$s</code>: <div class="highlight-php notranslate"><div class="highlight"><pre><?php p($l->t('Select file from %1$slocal filesystem%2$s or %3$scloud%4$s', ['<a href="#" id="browselink">', '</a>', '<a href="#" id="cloudlink">', '</a>']));?> </pre></div> </div> This allows translators to have the cloudlink before the browselink in case the language is e.g. right-to-left. </section> <section id="provide-context-hints-for-translators"> <h3>Provide context hints for translators<a class="headerlink" href="#provide-context-hints-for-translators" title="Link to this heading"></a></h3> 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: PHP <div class="highlight-php notranslate"><div class="highlight"><pre><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> </pre></div> </div> Javascript <div class="highlight-javascript notranslate"><div class="highlight"><pre>// TRANSLATORS name that is appended to copied files with the same name, will be put in parenthesis and appended with a number if it is the second+ copy var copyNameLocalized = t('files', 'copy'); </pre></div> </div> Vue This covers vue html templates in vue sfc components. For vue js code, see the javascript section. <div class="highlight-html notranslate"><div class="highlight"><pre><NcActionCheckbox :checked="isRequired">  {{ t('forms', 'Required') }} </NcActionCheckbox> </pre></div> </div> C++ (Qt) <div class="highlight-c++ notranslate"><div class="highlight"><pre>//: Example text: "Progress of sync process. Shows the currently synced filename" fileProgressString = tr("Syncing %1").arg(allFilenames); </pre></div> </div> Android Strings <div class="highlight-xml notranslate"><div class="highlight"><pre> <string name="simple_boards">Boards</string> </pre></div> </div> iOS <div class="highlight-swift notranslate"><div class="highlight"><pre>/* The title on the navigation bar of the Scanning screen. */ "wescan.scanning.title" = "Scanning"; </pre></div> </div> </section> </section> <section id="adding-translations"> <h2>Adding translations<a class="headerlink" href="#adding-translations" title="Link to this heading"></a></h2> Nextcloud’s translation system is powered by <a class="reference external" href="https://explore.transifex.com/nextcloud/">Transifex</a>. To start translating sign up and enter a group. If your community app should be translated by the <a class="reference external" href="https://explore.transifex.com/nextcloud/">Nextcloud community on Transifex</a> just follow the setup section below. <section id="translation-tool"> <h3>Translation tool<a class="headerlink" href="#translation-tool" title="Link to this heading"></a></h3> 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 <code class="file docutils literal notranslate">.l10nignore</code> into the root folder of your app and specify the files one per line: <div class="highlight-default notranslate"><div class="highlight"><pre># compiled vue templates js/bruteforcesettings.js </pre></div> </div> </section> <section id="setup-of-the-transifex-sync"> <h3>Setup of the transifex sync<a class="headerlink" href="#setup-of-the-transifex-sync" title="Link to this heading"></a></h3> To setup the transifex sync within the Nextcloud community you need to add first the transifex config to your app folder at <code class="file docutils literal notranslate">.tx/config</code> (please replace MYAPP with your apps id): <div class="highlight-ini notranslate"><div class="highlight"><pre>[main] host = https://www.transifex.com lang_map = th_TH: th, ja_JP: ja, bg_BG: bg, cs_CZ: cs, fi_FI: fi, hu_HU: hu, nb_NO: nb, sk_SK: sk [o:nextcloud:p:nextcloud:r:MYAPP] file_filter = translationfiles/<lang>/MYAPP.po source_file = translationfiles/templates/MYAPP.pot source_lang = en type = PO </pre></div> </div> Then create a folder <code class="file docutils literal notranslate">l10n</code> and a file <code class="file docutils literal notranslate">l10n/.gitkeep</code> to create an empty folder which later holds the translations. Add one more file called <code class="file docutils literal notranslate">.l10nignore</code> in root of the repository and the files and folders to ignore for translations. Mostly used to ignore packed js files. Now the GitHub account <a class="reference external" href="https://github.com/nextcloud-bot">@nextcloud-bot</a> needs to get <code class="docutils literal notranslate">write</code> access to your repository. You can invite it from your repository settings: <blockquote> <div><code class="docutils literal notranslate">https://github.com/<user-name>/<repo-name>/settings/access</code> </div></blockquote> After sending the invitation, please <a class="reference external" href="https://github.com/nextcloud/docker-ci/issues/new/choose">open a ticket using the “Request translations” template</a>. The bot will run every night and only push commits to the following branches branch once there is an update to the translation: <ul class="simple"> <li>main</li> <li>master</li> <li>stableX (X being the recent 3 versions of Nextcloud Server)</li> </ul> You can overwrite this list by creating a file <code class="docutils literal notranslate">.tx/backport</code> in your repository with the following content: <div class="highlight-default notranslate"><div class="highlight"><pre>develop stable </pre></div> </div> That would sync the translations for the branches (<code class="docutils literal notranslate">main</code> and <code class="docutils literal notranslate">master</code> are added automatically): <ul class="simple"> <li>main</li> <li>master</li> <li>develop</li> <li>stable</li> </ul> <div class="admonition note"> Note In general you should enable the <a class="reference external" href="https://help.github.com/articles/configuring-protected-branches/">protected branches feature</a> for those branches. If you do that, you need to grant the <a class="reference external" href="https://github.com/nextcloud-bot">@nextcloud-bot</a> <code class="docutils literal notranslate">admin</code> permissions, but that is only possible for repositories owned by organizations. You can <a class="reference external" href="https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/creating-a-new-organization-from-scratch">create your own organization</a> </div> If you need help just <a class="reference external" href="https://github.com/nextcloud/docker-ci/issues/new/choose">open a ticket with the request</a> and we can also guide you through the steps. </section> <section id="manual-translation"> <h3>Manual translation<a class="headerlink" href="#manual-translation" title="Link to this heading"></a></h3> If Transifex is not the right choice or the app is not accepted for translation, generate the gettext strings by yourself by executing our <a class="reference external" href="https://github.com/nextcloud/docker-ci/tree/master/translations/translationtool">translation tool</a> in the app folder: <div class="highlight-default notranslate"><div class="highlight"><pre>cd /srv/http/nextcloud/apps/myapp translationtool.phar create-pot-files </pre></div> </div> The translation tool requires gettext, installable via: <div class="highlight-default notranslate"><div class="highlight"><pre>apt-get install gettext </pre></div> </div> The above tool generates a template that can be used to translate all strings of an app. This template is located in the folder <code class="file docutils literal notranslate">translationfiles/template/</code> with the name <code class="file docutils literal notranslate">myapp.pot</code>. It can be used by your favored translation tool which then creates a <code class="file docutils literal notranslate">.po</code> file. The <code class="file docutils literal notranslate">.po</code> file needs to be placed in a folder named like the language code with the app name as filename - for example <code class="file docutils literal notranslate">translationfiles/es/myapp.po</code>. 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: <div class="highlight-default notranslate"><div class="highlight"><pre>translationtool.phar convert-po-files </pre></div> </div> Now the following folder structure is available: <div class="highlight-default notranslate"><div class="highlight"><pre>myapp/l10n |-- es.js |-- es.json myapp/translationfiles |-- es | |-- myapp.po |-- templates |-- myapp.pot </pre></div> </div> You then just need the <code class="file docutils literal notranslate">.json</code> and <code class="file docutils literal notranslate">.js</code> files for a working localized app. </section> </section> </section> </div> </div> <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer"> <a href="css.html" class="btn btn-neutral float-left" title="CSS" accesskey="p" rel="prev"> Previous</a> <a href="theming.html" class="btn btn-neutral float-right" title="Theming support" accesskey="n" rel="next">Next </a> </div> <hr/> <div role="contentinfo"> © Copyright 2024 Nextcloud GmbH. </div> </footer> </div> </div> </section> </div> <script> jQuery(function () { SphinxRtdTheme.Navigation.enable(true); }); </script> </body> </html>