docs(design): add translator comments section to UX writing guide

Explains when and how to write TRANSLATORS comments in PHP, JS/TS,
Vue templates, and Vue script blocks, with examples from the server codebase.

Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>

Author: skjnldsv

developer_manual/design/writing.rst

@@ -111,6 +111,55 @@ Make sure the string still makes sense in all languages — word order differs a
    // Avoid — concatenation breaks translation
    $l->t('Shared with ') . $userName;
 
+Translator comments
+-------------------
+
+When a string is ambiguous or contains placeholders, add a ``TRANSLATORS`` comment on the line immediately before the translatable string.
+The comment is extracted by the translation tooling and shown to translators in Transifex.
+
+**When to add one:**
+
+- The string is ambiguous out of context (e.g. a single word with multiple meanings).
+- The string contains a placeholder — explain what the placeholder will be replaced with and give an example value where helpful.
+- The string describes a UI element or workflow that is not obvious from the text alone.
+
+**PHP** — place the comment on the line before the ``->t()`` call:
+
+.. code-block:: php
+
+   // TRANSLATORS The placeholder refers to the software product name, e.g. "Add to your Nextcloud"
+   $l->t('Add to your %s', [$productName]);
+
+**JavaScript / TypeScript** — same rule, line before the ``t()`` call:
+
+.. code-block:: javascript
+
+   // TRANSLATORS: This is the number of hidden files or folders
+   const hiddenSummary = n('files', '%n hidden', '%n hidden', hidden)
+
+   // TRANSLATORS: {relativeDueDate} will be replaced with a relative time, e.g. "2 hours ago" or "in 3 days"
+   t('files_reminders', 'We will remind you of this file {relativeDueDate}', { relativeDueDate })
+
+**Vue template** — use an HTML comment on the line above the element:
+
+.. code-block:: html
+
+   <!-- TRANSLATORS: Background using a single color -->
+   <span>{{ t('theming', 'Plain background') }}</span>
+
+In the ``<script>`` block of a Vue file, use the same ``//`` style as JavaScript.
+
+**Multi-line** — use when the context needs more than one sentence or lists example output:
+
+.. code-block:: php
+
+   // TRANSLATORS
+   // Indicates when a calendar event will happen, shown on invitation emails.
+   // Output example: "In 1 hour on July 1, 2024 for the entire day"
+   $l->t('In %1$s on %2$s for the entire day', [$relativeTime, $date]);
+
+Keep comments factual and brief. State what the placeholder contains and where the string appears. Do not repeat the string itself.
+
 Translatable strings
 --------------------