{"action":"created","comment":{"url":"https://api.github.com/repos/phpbb/documentation/pulls/comments/31390820","id":31390820,"diff_hunk":"@@ -8,48 +8,96 @@ also a requirement for Extensions to use said system for all output presented to\n the user. This chapter will show you how to use the language system and how to\n add your custom entries.\n \n+We generally refer to the name of the word in the dictionary as\n+**language key** or **language variable**, to the returned value as\n+**language value** or **language string**. Both together are a\n+**language entry**. Language entries are collected in language files.\n+\n+.. note::\n+\n+    By convention, the language key should always be all-uppercase, using\n+    underscores to separate words.\n \n Using the Language System in php\n ================================\n \n-The object holding the language dictionary for the current user is - hardly\n-surprising - the ``$user`` object. We generally refer to the name of the word in\n-the dictionary as **language key**, to the returned value as **language string**\n-or **language value**. Both together are a **language entry**. By convention,\n-the language key should always be all-uppercase. Language entries are collected\n-in language files.\n+The object holding the language dictionary for the current user is the ``$user``\n+object (``phpbb\\language\\language`` class). To get the translation of a language\n+entry inside of php code, call the ``phpbb\\language\\language::lang()`` method:\n+\n+.. code-block:: php\n+\n+    $language->lang('LANG_KEY');\n+\n+You can also insert values into translated string. Use ``%s`` as placeholders\n+for string in the language string and ``%d`` for integers:\n+\n+.. code-block:: php\n+\n+    // Language string: \"My translation has a %s\"\n+    echo $language->lang('LANG_KEY', 'parameter');\n+    // Output: \"My translation has a parameter\"\n+\n+    // Language string: \"My translation has %d parameter\"\n+    echo $language->lang('LANG_KEY', 1);\n+    // Output: \"My translation has 1 parameter\"\n+\n+.. warning::\n+\n+    When using ``%d`` for plurals make sure to allow translators to use plurals\n+    according to their language. For more information see: :doc:`plurals`\n+\n+.. note::\n \n-To lookup a language entry inside of phpBB, query the ``$user`` object like\n-this: ``$user->lang('LANG_KEY')``, which will return the language string\n-assigned to the key ``LANG_KEY`` in the current user's language. Note that many\n-functions in phpBB automatically translate their arguments; passing the language\n-key as an argument is usually enough.\n+    Many functions in phpBB automatically translate their arguments; passing the\n+    language key as an argument is usually enough.\n \n The dictionary is not loaded into memory all at once, but is split up in several\n files, which have to be manually loaded on demand. The files are stored inside\n the language directory, named after its\n-`language tag <https://area51.phpbb.com/docs/30x/coding-guidelines.html#translation>`_,\n+`language tag <https://area51.phpbb.com/docs/master/coding-guidelines.html#translation>`_,\n where one subdirectory is used for each installed language. The default language\n files are in the root of that subdirectory, while ACP language files go into the\n ``/acp`` subdirectory; email templates are placed in the ``/email``\n-subdirectory. Files for extensions should be placed in the extension's\n-``/language`` directory.\n+subdirectory.\n+\n+.. note::\n+    Files for extensions should be placed in the extension's ``/language``\n+    directory.\n+\n+Loading language files\n+======================\n+\n+Loading from phpBB core\n+-----------------------\n \n Additional language files can be loaded during user setup via the call to the\n-``$user->setup()`` method at the top of each accessible file. To do so, pass the\n-name with the subdirectory but without extension as argument of setup. For\n-instance ``$user->setup('search')`` or ``$user->setup('mylangfile')`` or\n-``$user->setup(array('mylangfile', 'search'))``. If you need to add a language\n-file at a later stage, use add_lang, e.g.\n-``$user->add_lang(array('mylangfile', 'search'))``.\n+``phpbb\\user::setup()`` method at the top of each accessible file. To do so,\n+pass the name with the subdirectory but without extension as argument of setup.\n+\n+.. code-block:: php\n \n-A sightly more difficult situation arises when the displayed text should contain\n-links etc. phpBB uses a ``lang()``-method for that, for instance:\n+    $user->setup('search')\n+    // or\n+    $user->setup('ucp')\n+    // or\n+    $user->setup(array('ucp', 'search'))\n+\n+Since ``phpbb\\user::setup()`` must only be called once,\n+``phpbb\\language\\language::add_lang()`` has to be used, to load additional\n+language files, after ``phpbb\\user::setup()`` has already been called.\n+\n+Loading from an extension\n+-------------------------\n+\n+To load a file from an extension\n+you need to use ``phpbb\\language\\language::add_lang_ext()`` which takes\n+the vendor + extension name as first argument and the array of language files as\n+a second argument.\n \n .. code-block:: php\n \n-    $message .= '<br /><br />' . $user->lang('MY_TRICKY_LANGUAGE_KEY', '<a href=\"' . append_sid(\"{$phpbb_root_path}mypage.$phpEx\") . '\">', '</a>');\n-    trigger_error($message);\n+    $language->add_lang_ext('acme/demo', array('demo'));","path":"development/language/usage.rst","position":117,"original_position":117,"commit_id":"6bf972a5a69aefde375ad737a10df2491540cd0e","original_commit_id":"6bf972a5a69aefde375ad737a10df2491540cd0e","user":{"login":"MateBartus","id":10946388,"avatar_url":"https://avatars.githubusercontent.com/u/10946388?v=3","gravatar_id":"","url":"https://api.github.com/users/MateBartus","html_url":"https://github.com/MateBartus","followers_url":"https://api.github.com/users/MateBartus/followers","following_url":"https://api.github.com/users/MateBartus/following{/other_user}","gists_url":"https://api.github.com/users/MateBartus/gists{/gist_id}","starred_url":"https://api.github.com/users/MateBartus/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MateBartus/subscriptions","organizations_url":"https://api.github.com/users/MateBartus/orgs","repos_url":"https://api.github.com/users/MateBartus/repos","events_url":"https://api.github.com/users/MateBartus/events{/privacy}","received_events_url":"https://api.github.com/users/MateBartus/received_events","type":"User","site_admin":false},"body":"``$language->add_lang(array('demo'), 'acme/demo');``","created_at":"2015-05-31T14:42:26Z","updated_at":"2015-05-31T14:42:26Z","html_url":"https://github.com/phpbb/documentation/pull/38#discussion_r31390820","pull_request_url":"https://api.github.com/repos/phpbb/documentation/pulls/38","_links":{"self":{"href":"https://api.github.com/repos/phpbb/documentation/pulls/comments/31390820"},"html":{"href":"https://github.com/phpbb/documentation/pull/38#discussion_r31390820"},"pull_request":{"href":"https://api.github.com/repos/phpbb/documentation/pulls/38"}}},"pull_request":{"url":"https://api.github.com/repos/phpbb/documentation/pulls/38","id":36583067,"html_url":"https://github.com/phpbb/documentation/pull/38","diff_url":"https://github.com/phpbb/documentation/pull/38.diff","patch_url":"https://github.com/phpbb/documentation/pull/38.patch","issue_url":"https://api.github.com/repos/phpbb/documentation/issues/38","number":38,"state":"open","locked":false,"title":"Issue/21 language system changes in 3.2","user":{"login":"nickvergessen","id":213943,"avatar_url":"https://avatars.githubusercontent.com/u/213943?v=3","gravatar_id":"","url":"https://api.github.com/users/nickvergessen","html_url":"https://github.com/nickvergessen","followers_url":"https://api.github.com/users/nickvergessen/followers","following_url":"https://api.github.com/users/nickvergessen/following{/other_user}","gists_url":"https://api.github.com/users/nickvergessen/gists{/gist_id}","starred_url":"https://api.github.com/users/nickvergessen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nickvergessen/subscriptions","organizations_url":"https://api.github.com/users/nickvergessen/orgs","repos_url":"https://api.github.com/users/nickvergessen/repos","events_url":"https://api.github.com/users/nickvergessen/events{/privacy}","received_events_url":"https://api.github.com/users/nickvergessen/received_events","type":"User","site_admin":false},"body":"- [ ] Depends on #36 \r\n\r\n@MateBartus please review https://github.com/phpbb/documentation/commit/6bf972a5a69aefde375ad737a10df2491540cd0e","created_at":"2015-05-31T14:28:45Z","updated_at":"2015-05-31T14:42:26Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a2ca01db147440754c4c79c70d9cf89e3b75d6dc","assignee":null,"milestone":{"url":"https://api.github.com/repos/phpbb/documentation/milestones/1","html_url":"https://github.com/phpbb/documentation/milestones/3.2.0","labels_url":"https://api.github.com/repos/phpbb/documentation/milestones/1/labels","id":1138127,"number":1,"title":"3.2.0","description":"","creator":{"login":"nickvergessen","id":213943,"avatar_url":"https://avatars.githubusercontent.com/u/213943?v=3","gravatar_id":"","url":"https://api.github.com/users/nickvergessen","html_url":"https://github.com/nickvergessen","followers_url":"https://api.github.com/users/nickvergessen/followers","following_url":"https://api.github.com/users/nickvergessen/following{/other_user}","gists_url":"https://api.github.com/users/nickvergessen/gists{/gist_id}","starred_url":"https://api.github.com/users/nickvergessen/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nickvergessen/subscriptions","organizations_url":"https://api.github.com/users/nickvergessen/orgs","repos_url":"https://api.github.com/users/nickvergessen/repos","events_url":"https://api.github.com/users/nickvergessen/events{/privacy}","received_events_url":"https://api.github.com/users/nickvergessen/received_events","type":"User","site_admin":false},"open_issues":2,"closed_issues":1,"state":"open","created_at":"2015-05-28T14:17:59Z","updated_at":"2015-05-31T14:28:45Z","due_on":null,"closed_at":null},"commits_url":"https://api.github.com/repos/phpbb/documentation/pulls/38/commits","review_comments_url":"https://api.github.com/repos/phpbb/documentation/pulls/38/comments","review_comment_url":"https://api.github.com/repos/phpbb/documentation/pulls/comments{/number}","comments_url":"https://api.github.com/repos/phpbb/documentation/issues/38/comments","statuses_url":"https://api.github.com/repos/phpbb/documentation/statuses/6bf972a5a69aefde375ad737a10df2491540cd0e","head":{"label":"nickv-phpbb:issue/21-language-system-changes-in-3.2","ref":"issue/21-language-system-changes-in-3.2","sha":"6bf972a5a69aefde375ad737a10df2491540cd0e","user":{"login":"nickv-phpbb","id":10869423,"avatar_url":"https://avatars.githubusercontent.com/u/10869423?v=3","gravatar_id":"","url":"https://api.github.com/users/nickv-phpbb","html_url":"https://github.com/nickv-phpbb","followers_url":"https://api.github.com/users/nickv-phpbb/followers","following_url":"https://api.github.com/users/nickv-phpbb/following{/other_user}","gists_url":"https://api.github.com/users/nickv-phpbb/gists{/gist_id}","starred_url":"https://api.github.com/users/nickv-phpbb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nickv-phpbb/subscriptions","organizations_url":"https://api.github.com/users/nickv-phpbb/orgs","repos_url":"https://api.github.com/users/nickv-phpbb/repos","events_url":"https://api.github.com/users/nickv-phpbb/events{/privacy}","received_events_url":"https://api.github.com/users/nickv-phpbb/received_events","type":"Organization","site_admin":false},"repo":{"id":36438077,"name":"documentation","full_name":"nickv-phpbb/documentation","owner":{"login":"nickv-phpbb","id":10869423,"avatar_url":"https://avatars.githubusercontent.com/u/10869423?v=3","gravatar_id":"","url":"https://api.github.com/users/nickv-phpbb","html_url":"https://github.com/nickv-phpbb","followers_url":"https://api.github.com/users/nickv-phpbb/followers","following_url":"https://api.github.com/users/nickv-phpbb/following{/other_user}","gists_url":"https://api.github.com/users/nickv-phpbb/gists{/gist_id}","starred_url":"https://api.github.com/users/nickv-phpbb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nickv-phpbb/subscriptions","organizations_url":"https://api.github.com/users/nickv-phpbb/orgs","repos_url":"https://api.github.com/users/nickv-phpbb/repos","events_url":"https://api.github.com/users/nickv-phpbb/events{/privacy}","received_events_url":"https://api.github.com/users/nickv-phpbb/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/nickv-phpbb/documentation","description":"Documentation for end-users: board visitors, moderators and administrators","fork":true,"url":"https://api.github.com/repos/nickv-phpbb/documentation","forks_url":"https://api.github.com/repos/nickv-phpbb/documentation/forks","keys_url":"https://api.github.com/repos/nickv-phpbb/documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/nickv-phpbb/documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/nickv-phpbb/documentation/teams","hooks_url":"https://api.github.com/repos/nickv-phpbb/documentation/hooks","issue_events_url":"https://api.github.com/repos/nickv-phpbb/documentation/issues/events{/number}","events_url":"https://api.github.com/repos/nickv-phpbb/documentation/events","assignees_url":"https://api.github.com/repos/nickv-phpbb/documentation/assignees{/user}","branches_url":"https://api.github.com/repos/nickv-phpbb/documentation/branches{/branch}","tags_url":"https://api.github.com/repos/nickv-phpbb/documentation/tags","blobs_url":"https://api.github.com/repos/nickv-phpbb/documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/nickv-phpbb/documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/nickv-phpbb/documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/nickv-phpbb/documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/nickv-phpbb/documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/nickv-phpbb/documentation/languages","stargazers_url":"https://api.github.com/repos/nickv-phpbb/documentation/stargazers","contributors_url":"https://api.github.com/repos/nickv-phpbb/documentation/contributors","subscribers_url":"https://api.github.com/repos/nickv-phpbb/documentation/subscribers","subscription_url":"https://api.github.com/repos/nickv-phpbb/documentation/subscription","commits_url":"https://api.github.com/repos/nickv-phpbb/documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/nickv-phpbb/documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/nickv-phpbb/documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/nickv-phpbb/documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/nickv-phpbb/documentation/contents/{+path}","compare_url":"https://api.github.com/repos/nickv-phpbb/documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/nickv-phpbb/documentation/merges","archive_url":"https://api.github.com/repos/nickv-phpbb/documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/nickv-phpbb/documentation/downloads","issues_url":"https://api.github.com/repos/nickv-phpbb/documentation/issues{/number}","pulls_url":"https://api.github.com/repos/nickv-phpbb/documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/nickv-phpbb/documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/nickv-phpbb/documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/nickv-phpbb/documentation/labels{/name}","releases_url":"https://api.github.com/repos/nickv-phpbb/documentation/releases{/id}","created_at":"2015-05-28T12:52:01Z","updated_at":"2015-05-29T08:55:51Z","pushed_at":"2015-05-31T14:35:59Z","git_url":"git://github.com/nickv-phpbb/documentation.git","ssh_url":"git@github.com:nickv-phpbb/documentation.git","clone_url":"https://github.com/nickv-phpbb/documentation.git","svn_url":"https://github.com/nickv-phpbb/documentation","homepage":"http://www.phpbb.com","size":7587,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"phpbb:master","ref":"master","sha":"8f1084e622e4843bf8bed67769f48cfbdfbf1654","user":{"login":"phpbb","id":176697,"avatar_url":"https://avatars.githubusercontent.com/u/176697?v=3","gravatar_id":"","url":"https://api.github.com/users/phpbb","html_url":"https://github.com/phpbb","followers_url":"https://api.github.com/users/phpbb/followers","following_url":"https://api.github.com/users/phpbb/following{/other_user}","gists_url":"https://api.github.com/users/phpbb/gists{/gist_id}","starred_url":"https://api.github.com/users/phpbb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/phpbb/subscriptions","organizations_url":"https://api.github.com/users/phpbb/orgs","repos_url":"https://api.github.com/users/phpbb/repos","events_url":"https://api.github.com/users/phpbb/events{/privacy}","received_events_url":"https://api.github.com/users/phpbb/received_events","type":"Organization","site_admin":false},"repo":{"id":2660622,"name":"documentation","full_name":"phpbb/documentation","owner":{"login":"phpbb","id":176697,"avatar_url":"https://avatars.githubusercontent.com/u/176697?v=3","gravatar_id":"","url":"https://api.github.com/users/phpbb","html_url":"https://github.com/phpbb","followers_url":"https://api.github.com/users/phpbb/followers","following_url":"https://api.github.com/users/phpbb/following{/other_user}","gists_url":"https://api.github.com/users/phpbb/gists{/gist_id}","starred_url":"https://api.github.com/users/phpbb/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/phpbb/subscriptions","organizations_url":"https://api.github.com/users/phpbb/orgs","repos_url":"https://api.github.com/users/phpbb/repos","events_url":"https://api.github.com/users/phpbb/events{/privacy}","received_events_url":"https://api.github.com/users/phpbb/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/phpbb/documentation","description":"Documentation for end-users: board visitors, moderators and administrators","fork":false,"url":"https://api.github.com/repos/phpbb/documentation","forks_url":"https://api.github.com/repos/phpbb/documentation/forks","keys_url":"https://api.github.com/repos/phpbb/documentation/keys{/key_id}","collaborators_url":"https://api.github.com/repos/phpbb/documentation/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/phpbb/documentation/teams","hooks_url":"https://api.github.com/repos/phpbb/documentation/hooks","issue_events_url":"https://api.github.com/repos/phpbb/documentation/issues/events{/number}","events_url":"https://api.github.com/repos/phpbb/documentation/events","assignees_url":"https://api.github.com/repos/phpbb/documentation/assignees{/user}","branches_url":"https://api.github.com/repos/phpbb/documentation/branches{/branch}","tags_url":"https://api.github.com/repos/phpbb/documentation/tags","blobs_url":"https://api.github.com/repos/phpbb/documentation/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/phpbb/documentation/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/phpbb/documentation/git/refs{/sha}","trees_url":"https://api.github.com/repos/phpbb/documentation/git/trees{/sha}","statuses_url":"https://api.github.com/repos/phpbb/documentation/statuses/{sha}","languages_url":"https://api.github.com/repos/phpbb/documentation/languages","stargazers_url":"https://api.github.com/repos/phpbb/documentation/stargazers","contributors_url":"https://api.github.com/repos/phpbb/documentation/contributors","subscribers_url":"https://api.github.com/repos/phpbb/documentation/subscribers","subscription_url":"https://api.github.com/repos/phpbb/documentation/subscription","commits_url":"https://api.github.com/repos/phpbb/documentation/commits{/sha}","git_commits_url":"https://api.github.com/repos/phpbb/documentation/git/commits{/sha}","comments_url":"https://api.github.com/repos/phpbb/documentation/comments{/number}","issue_comment_url":"https://api.github.com/repos/phpbb/documentation/issues/comments{/number}","contents_url":"https://api.github.com/repos/phpbb/documentation/contents/{+path}","compare_url":"https://api.github.com/repos/phpbb/documentation/compare/{base}...{head}","merges_url":"https://api.github.com/repos/phpbb/documentation/merges","archive_url":"https://api.github.com/repos/phpbb/documentation/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/phpbb/documentation/downloads","issues_url":"https://api.github.com/repos/phpbb/documentation/issues{/number}","pulls_url":"https://api.github.com/repos/phpbb/documentation/pulls{/number}","milestones_url":"https://api.github.com/repos/phpbb/documentation/milestones{/number}","notifications_url":"https://api.github.com/repos/phpbb/documentation/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/phpbb/documentation/labels{/name}","releases_url":"https://api.github.com/repos/phpbb/documentation/releases{/id}","created_at":"2011-10-27T19:22:20Z","updated_at":"2015-05-28T10:33:20Z","pushed_at":"2015-05-31T14:35:59Z","git_url":"git://github.com/phpbb/documentation.git","ssh_url":"git@github.com:phpbb/documentation.git","clone_url":"https://github.com/phpbb/documentation.git","svn_url":"https://github.com/phpbb/documentation","homepage":"http://www.phpbb.com","size":8025,"stargazers_count":7,"watchers_count":7,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":36,"mirror_url":null,"open_issues_count":8,"forks":36,"open_issues":8,"watchers":7,"default_branch":"3.1.x"}},"_links":{"self":{"href":"https://api.github.com/repos/phpbb/documentation/pulls/38"},"html":{"href":"https://github.com/phpbb/documentation/pull/38"},"issue":{"href":"https://api.github.com/repos/phpbb/documentation/issues/38"},"comments":{"href":"https://api.github.com/repos/phpbb/documentation/issues/38/comments"},"review_comments":{"href":"https://api.github.com/repos/phpbb/documentation/pulls/38/comments"},"review_comment":{"href":"https://api.github.com/repos/phpbb/documentation/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/phpbb/documentation/pulls/38/commits"},"statuses":{"href":"https://api.github.com/repos/phpbb/documentation/statuses/6bf972a5a69aefde375ad737a10df2491540cd0e"}}}}