Merge pull request #15295 from nextcloud/fix/noid/translators-string

fix(developer): add note about multiple translation strings per line

Author: rakekniven

developer_manual/basics/translations.rst

@@ -283,6 +283,26 @@ Especially translations strings that only contain a single word often result in
 The most famous example in the Nextcloud code base is ``Share`` which can which can be the verb and action ``To share something`` or the noun ``A share``.
 The added hints will be shown in the Transifex web-interface:
 
+.. warning::
+
+   A ``// TRANSLATORS`` comment is only associated with the **first** translation string on the following line.
+   If a single line of code contains two or more translation strings, the comment applies to the first one only,
+   and the remaining strings will have no context hint. Refactor the code so that each line holds a single
+   translation call, placing its own ``// TRANSLATORS`` comment on the line above.
+
+   .. code-block:: php
+
+       // BAD: only "Save" gets the context hint, "Cancel" has none
+       // TRANSLATORS Confirm or discard the current changes
+       return [$l->t('Save'), $l->t('Cancel')];
+
+       // GOOD: one translation per line, each with its own hint
+       // TRANSLATORS Confirm the current changes
+       $save = $l->t('Save');
+       // TRANSLATORS Discard the current changes
+       $cancel = $l->t('Cancel');
+       return [$save, $cancel];
+
 PHP
 """