docs(design): split translator hints between writing guide and translations ref

Move code examples for TRANSLATORS comments to basics/translations.rst
(the implementation reference) and keep only prose guidelines in
design/writing.rst. Cross-link both directions so neither page duplicates
the other.

- writing.rst: strip code blocks from Translator comments and Placeholders
  sections; add cross-refs to translations.rst
- translations.rst: improve PHP/JS/Vue TRANSLATORS examples (Vue template
  uses <!-- --> above element, add multi-line PHP pattern); add ref label
  improving-translations for cross-linking

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

Author: skjnldsv

developer_manual/basics/translations.rst

@@ -220,6 +220,8 @@ JS Example:
     /* BEST: Simple string with undefined plural not using any number in the string */
     t('myapp', 'Import calendars')
 
+.. _improving-translations:
+
 Improving your translations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -284,37 +286,49 @@ The added hints will be shown in the Transifex web-interface:
 PHP
 """
 
+Place the comment on the line before the ``->t()`` or ``->n()`` call:
+
+.. code-block:: php
+
+    // TRANSLATORS Will be shown inside a popup and asks the user to add a new file
+    p($l->t('Add new file'));
+
+    // TRANSLATORS The placeholder refers to the software product name, e.g. "Add to your Nextcloud"
+    $l->t('Add to your %s', [$productName]);
+
+For multi-line context or example output, use consecutive comment lines:
+
 .. code-block:: php
 
-    <ul id="translations">
-        <li id="add-new">
-            <?php
-                // TRANSLATORS Will be shown inside a popup and asks the user to add a new file
-                p($l->t('Add new file'));
-            ?>
-        </li>
-    </ul>
+    // 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]);
 
 JavaScript / TypeScript
 """""""""""""""""""""""
 
+Place the comment on the line before the ``t()`` or ``n()`` call:
+
 .. code-block:: javascript
 
-    // TRANSLATORS name that is appended to copied files with the same name, will be put in parenthesis and appended with a number if it is the second+ copy
+    // TRANSLATORS: name that is appended to copied files, will be put in parenthesis with a number for the second+ copy
     var copyNameLocalized = t('files', 'copy');
 
+    // 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
 """
 
-This covers vue html templates in vue sfc components.
-For vue js code, see the javascript section.
+In the ``<template>`` block, use an HTML comment on the line above the element:
 
 .. code-block:: html
 
-    <NcActionCheckbox :checked="isRequired">
-        <!-- TRANSLATORS Making this question necessary to be answered when submitting to a form -->
-        {{ t('forms', 'Required') }}
-    </NcActionCheckbox>
+    <!-- TRANSLATORS: Making this question necessary to be answered when submitting to a form -->
+    <span>{{ t('forms', 'Required') }}</span>
+
+In the ``<script>`` block, use the same ``//`` style as JavaScript.
 
 C++ (Qt) / Desktop client
 """""""""""""""""""""""""

developer_manual/design/writing.rst

@@ -102,63 +102,26 @@ Placeholders and variables
 
 When a string contains a variable (file name, user name, count), keep the surrounding text short and natural.
 Make sure the string still makes sense in all languages — word order differs across languages, so avoid splitting a sentence across two separate strings.
+For implementation details and code examples, see :ref:`improving-translations` in the translations reference.
 
-.. code-block:: php
-
-   // Good — full sentence in one string, variable embedded
-   $l->t('Shared with %s', [$userName]);
-
-   // Avoid — concatenation breaks translation
-   $l->t('Shared with ') . $userName;
+.. _translator-comments:
 
 Translator comments
 -------------------
 
-When a string is ambiguous or contains placeholders, add a ``TRANSLATORS`` comment on the line immediately before the translatable string.
+When a string is ambiguous or contains placeholders, add a ``TRANSLATORS`` comment immediately before the translatable call.
 The comment is extracted by the translation tooling and shown to translators in Transifex.
 
-**When to add one:**
+Add one when:
 
 - 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 contains a placeholder — explain what it will be replaced with and give an example value.
 - 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.
 
-Keep comments factual and brief. State what the placeholder contains and where the string appears. Do not repeat the string itself.
+For syntax examples in PHP, JavaScript, Vue, and other platforms, see :ref:`Hints`.
 
 Translatable strings
 --------------------