From 6a68df5fd13101e095059460542a88bc4d6910dd Mon Sep 17 00:00:00 2001
From: Eike Ziller
Date: Mon, 27 May 2024 12:03:13 +0200
Subject: [PATCH] UI guidelines: Update the rules for localization
We switched to single contexts with Tr::tr and have
FilePath::toUserOutput now, adapt the rules accordingly.
Change-Id: Ie73b8077dfd6bef56f709538db1d1b3ec7843041
Reviewed-by: Leena Miettinen
---
doc/qtcreatordev/src/qtcreator-ui-text.qdoc | 50 ++++++++++++++++-----
1 file changed, 38 insertions(+), 12 deletions(-)
diff --git a/doc/qtcreatordev/src/qtcreator-ui-text.qdoc b/doc/qtcreatordev/src/qtcreator-ui-text.qdoc
index f8332668ed2..e76ad238e23 100644
--- a/doc/qtcreatordev/src/qtcreator-ui-text.qdoc
+++ b/doc/qtcreatordev/src/qtcreator-ui-text.qdoc
@@ -273,8 +273,36 @@
\section2 Marking UI Text for Translation
- Make sure the text strings presented to the user are easy to translate.
- The user interface text strings are enclosed in \c tr() calls and
+ \section3 Translation Context
+
+ Avoid creating many different translation contexts. By default, \c tr()
+ uses the context of the class, which means that translations break when
+ code is refactored and UI text is moved to a different class.
+
+ Create a single translation context for each plugin instead. Create a header
+ \c myplugintr.h
+
+ \code
+ #pragma once
+
+ #include
+
+ namespace MyPlugin {
+
+ struct Tr
+ {
+ Q_DECLARE_TR_FUNCTIONS(QtC::MyPlugin)
+ };
+
+ } // namespace MyPlugin
+ \endcode
+
+ and use that struct as the translation context for UI text by calling
+ \c {Tr::tr()}. Use disambiguation strings in cases that need it.
+
+ \section3 Translator Comments
+
+ The user interface text strings are enclosed in \c {Tr::tr()} calls and
extracted from the source code during the translation process. Therefore,
the translator might not know the source code context of the messages.
@@ -286,26 +314,24 @@
return tr("Add");
\endcode
- If the class is not Q_OBJECT, use \c {QCoreApplication::translate("class
- context", "message")} or consider using Q_DECLARE_TR_FUNCTIONS. Do not use
- \c {QObject::tr()}, which is confusing because the messages appear grouped
- by class context in Qt Linguist and messages tied to QObject do not have a
- class context.
+ \section3 File Paths
- Use \c{QDir::toNativeSeparators()} for file and directory names that you
- pass to \c{tr().arg()}.
+ Use \c{FilePath::toUserOutput()} from the \c Utils library for file and directory
+ names that you pass to \c{Tr::tr().arg()}.
- Do not use markup that spans the whole string because that can be confusing
+ \section3 Markup
+
+ Avoid including markup within the translated text itself because that can be confusing
for translators. For example, instead of:
\code
- tr("UI Text")
+ Tr::tr("UI Text")
\endcode
use
\code
- QLatin1String("") + tr("UI Text") + QLatin1String("/span>")
+ "" + Tr::tr("UI Text") + ""
\endcode
\section2 Features of Languages or Writing Systems