Merge pull request #9314 from nextcloud/backport/9309/stable23stable23

[stable23] Document `IFactory::getUserLanguage()`

1 files changed, 44 insertions, 18 deletions

diff --git a/developer_manual/basics/front-end/l10n.rst b/developer_manual/basics/front-end/l10n.rst
index 6ac73b2f9..3a469104c 100644
--- a/developer_manual/basics/front-end/l10n.rst
+++ b/developer_manual/basics/front-end/l10n.rst
@@ -5,16 +5,10 @@ Translation
 .. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>, Kristof Hamann
 
 Nextcloud provides mechanisms for internationalization (make an application translatable) and localization (add translations for specific languages). This section provides detailed instructions for both aspects.
-
-
-Make text translatable
-----------------------
-
 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).
 
-
 PHP
-^^^
+---
 
 If localized strings are used in the backend code, simply inject the ``\OCP\IL10N`` class into your service via type hinting it in the constructor. You will automatically get the language object containing the translations of your app:
 
@@ -24,7 +18,7 @@ If localized strings are used in the backend code, simply inject the ``\OCP\IL10
     <?php
     namespace OCA\MyApp\Service;
 
-    use \OCP\IL10N;
+    use OCP\IL10N;
 
 
     class AuthorService {
@@ -76,7 +70,7 @@ Strings can then be translated in the following way:
     }
 
 Correct plurals
-"""""""""""""""
+^^^^^^^^^^^^^^^
 
 If you use a plural, you **must** also use the ``%n`` 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.
 
@@ -84,6 +78,8 @@ Example:
 
 .. code-block:: php
 
+    <?php
+
     // BAD: Plural without count
     $title = $l->n('Import calendar', 'Import calendars', $selectionLength)
     // BETTER: Plural has count, but disrupting to read and unnecessary information
@@ -91,9 +87,37 @@ Example:
     // BEST: Simple string with undefined plural
     $title = $l->t('Import calendars')
 
+Language of other users
+^^^^^^^^^^^^^^^^^^^^^^^
+
+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 ``force_language`` and ``default_language`` configuration options to consider. To make this easier, the
+``OCP\L10N\IFactory`` class comes with a ``getUserLanguage`` method:
+
+.. code-block:: php
+
+    <?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);
+
+            // …
+        }
+
 
 Templates
-^^^^^^^^^
+---------
 
 In every template the global variable **$l** can be used to translate the strings using its methods **t()** and **n()**:
 
@@ -108,7 +132,7 @@ For the right date format use ``<?php p($l->l('date', time()));?>``.
 
 
 JavaScript
-^^^^^^^^^^
+----------
 
 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:
 
@@ -125,12 +149,12 @@ There are global functions **t()** and **n()** available for translating strings
 
 
 Important notes
-^^^^^^^^^^^^^^^
+---------------
 
 Please also look through the following steps to improve your strings and make them better translatable by others
 
 Improving your translations
-"""""""""""""""""""""""""""
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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.
 
@@ -169,8 +193,10 @@ But there is one last problem with this. In case the language has to turn things
 
 This allows translators to have the cloudlink before the browselink in case the language is e.g. right-to-left.
 
-Hints
-"""""
+.. _Hints:
+
+Provide context hints for translators
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 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:
 
@@ -226,8 +252,6 @@ Adding translations
 
 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.
 
-
-
 Translation tool
 ^^^^^^^^^^^^^^^^
 
@@ -248,7 +272,9 @@ 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)::
+transifex config to your app folder at :file:`.tx/config` (please replace **MYAPP** with your apps id):
+
+.. code-block:: ini
 
     [main]
     host = https://www.transifex.com