diff --git a/developer_manual/basics/translations.rst b/developer_manual/basics/translations.rst
index 4ee51205f44..48b87450c38 100644
--- a/developer_manual/basics/translations.rst
+++ b/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
 """