[stable34] docs(design): add UX writing guide for user-facing strings#14997
Merged
Conversation
Adds a new writing.rst page to developer_manual/design/ covering tone, message brevity, the "successfully" anti-pattern, button label conventions, and variable/placeholder gotchas for translators. Linked from design/index.rst toctree. Relates to #13884 Signed-off-by: John Molakvoæ (skjnldsv) <skjnldsv@protonmail.com>
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>
…ations 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>
- Add Nextcloud naming rule (capital N, lowercase c, no NextCloud/Nc) - Add "never all uppercase" to sentence case rule with SHARE example - Add names, pronouns, and gender section (full names, avoid my/your, gender-neutral language with link to international guide) - Move destructive actions note above the button labels table Signed-off-by: skjnldsv <skjnldsv@protonmail.com>
backportbot
Bot
requested review from
jancborchardt,
nimishavijay,
rakekniven and
skjnldsv
jancborchardt
approved these changes
May 21, 2026
rakekniven
approved these changes
May 21, 2026
Contributor
📖 Documentation Preview📄 3 changed documentation pagesLast updated: Thu, 21 May 2026 11:16:33 GMT |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport of PR #14962