Add a sample how to load an extension language file

development/language/index.rst

@@ -4,5 +4,5 @@ Languages and translations
 .. toctree::
    :maxdepth: 2
 
-   plurals
    usage
+   plurals

development/language/usage.rst

@@ -8,66 +8,122 @@ also a requirement for Extensions to use said system for all output presented to
 the user. This chapter will show you how to use the language system and how to
 add your custom entries.
 
+We generally refer to the name of the word in the dictionary as
+**language key** or **language variable**, to the returned value as
+**language value** or **language string**. Both together are a
+**language entry**. Language entries are collected in language files.
+
+.. note::
+
+    By convention, the language key should always be all-uppercase, using
+    underscores to separate words.
 
 Using the Language System in php
 ================================
 
-The object holding the language dictionary for the current user is - hardly
-surprising - the ``$user`` object. We generally refer to the name of the word in
-the dictionary as **language key**, to the returned value as **language string**
-or **language value**. Both together are a **language entry**. By convention,
-the language key should always be all-uppercase. Language entries are collected
-in language files.
+The object holding the language dictionary for the current user is the ``$user``
+object (``phpbb\user`` class). To get the translation of a language entry inside
+of php code, call the ``phpbb\user::lang()`` method:
+
+.. code-block:: php
+
+    $user->lang('LANG_KEY');
+
+You can also insert values into translated string. Use ``%s`` as placeholders
+for string in the language string and ``%d`` for integers:
+
+.. code-block:: php
+
+    // Language string: "My translation has a %s"
+    echo $user->lang('LANG_KEY', 'parameter');
+    // Output: "My translation has a parameter"
+
+    // Language string: "My translation has %d parameter"
+    echo $user->lang('LANG_KEY', 1);
+    // Output: "My translation has 1 parameter"
+
+.. warning::
+
+    When using ``%d`` for plurals make sure to allow translators to use plurals
+    according to their language. For more information see: :doc:`plurals`
+
+.. note::
 
-To lookup a language entry inside of phpBB, query the ``$user`` object like
-this: ``$user->lang('LANG_KEY')``, which will return the language string
-assigned to the key ``LANG_KEY`` in the current user's language. Note that many
-functions in phpBB automatically translate their arguments; passing the language
-key as an argument is usually enough.
+    Many functions in phpBB automatically translate their arguments; passing the
+    language key as an argument is usually enough.
 
 The dictionary is not loaded into memory all at once, but is split up in several
 files, which have to be manually loaded on demand. The files are stored inside
 the language directory, named after its
-`language tag <https://area51.phpbb.com/docs/30x/coding-guidelines.html#translation>`_,
+`language tag <https://area51.phpbb.com/docs/31x/coding-guidelines.html#translation>`_,
 where one subdirectory is used for each installed language. The default language
 files are in the root of that subdirectory, while ACP language files go into the
 ``/acp`` subdirectory; email templates are placed in the ``/email``
-subdirectory. Files for extensions should be placed in the extension's
-``/language`` directory.
+subdirectory.
+
+.. note::
+    Files for extensions should be placed in the extension's ``/language``
+    directory.
+
+Loading language files
+======================
+
+Loading from phpBB core
+-----------------------
 
 Additional language files can be loaded during user setup via the call to the
-``$user->setup()`` method at the top of each accessible file. To do so, pass the
-name with the subdirectory but without extension as argument of setup. For
-instance ``$user->setup('search')`` or ``$user->setup('mylangfile')`` or
-``$user->setup(array('mylangfile', 'search'))``. If you need to add a language
-file at a later stage, use add_lang, e.g.
-``$user->add_lang(array('mylangfile', 'search'))``.
+``phpbb\user::setup()`` method at the top of each accessible file. To do so,
+pass the name with the subdirectory but without extension as argument of setup.
+
+.. code-block:: php
 
-A sightly more difficult situation arises when the displayed text should contain
-links etc. phpBB uses a ``lang()``-method for that, for instance:
+    $user->setup('search');
+    // or
+    $user->setup('ucp');
+    // or
+    $user->setup(array('ucp', 'search'));
+
+Since ``phpbb\user::setup()`` must only be called once,
+``phpbb\user::add_lang()`` has to be used, to load additional language files,
+after ``phpbb\user::setup()`` has already been called.
+
+Loading from an extension
+-------------------------
+
+To load a file from an extension
+you need to use ``phpbb\user::add_lang_ext()`` which takes
+the vendor + extension name as first argument and the array of language files as
+a second argument.
 
 .. code-block:: php
 
-    $message .= '<br /><br />' . $user->lang('MY_TRICKY_LANGUAGE_KEY', '<a href="' . append_sid("{$phpbb_root_path}mypage.$phpEx") . '">', '</a>');
-    trigger_error($message);
+    $user->add_lang_ext('acme/demo', 'demo');
+    // or
+    $user->add_lang_ext('acme/demo', array('demo', 'demo2'));
 
 Using the Language System in template files
 ===========================================
 
 Language entries in
 `Using the Template System <https://wiki.phpbb.com/Using_the_phpBB3.0_Template_System>`_
 are a major improvement since phpBB 3.0. There is no longer a need to manually
-assign these in the php file; loaded language files will be automatically used.
+assign these in the PHP file; language entries of loaded language files can be
+used automatically.
+
 To use the language entry with the key ``MY_KEY`` in a template file, just write
-``{L_MY_KEY}`` in the template - it's as simple as that.
+``{L_MY_KEY}`` in the template (phpBB syntax) or ``{{ lang('MY_KEY') }}`` (new
+twig syntax).
 
 Add new entries
 ===============
 
 New language files should always be placed in their own files in the extensions
-directory. There are however a few exceptions, notably log entries and module
-names. Those need to be placed in their appropriate common.php language file,
-either in the language's directory or the acp subdirectory.
+directory.
+
+.. note::
+
+    When defining log entries and module names, make sure to load the language
+    file, when the entries are being used.
 
 .. note::
 
@@ -80,6 +136,7 @@ either in the language's directory or the acp subdirectory.
 .. code-block:: php
 
     <?php
+    // language/en/sample.php
     /**
      *
      * This file is part of the phpBB Forum Software package.
@@ -113,7 +170,7 @@ either in the language's directory or the acp subdirectory.
     // in a url you again do not need to specify an order e.g., 'Click %sHERE%s' is fine
 
     $lang = array_merge($lang, array(
-        'MY_LANGUAGE_KEY'		=> 'A language entry',
-        'MY_OTHER_LANGUAGE_KEY'	=> 'Another language entry',
-        'MY_TRICKY_LANGUAGE_KEY'	=> 'This is a %slink%s',
+        'MY_LANGUAGE_KEY'         => 'A language entry',
+        'MY_OTHER_LANGUAGE_KEY'   => 'Another language entry',
+        'MY_TRICKY_LANGUAGE_KEY'  => 'This is a %slink%s',
     ));