Add additional advice about translating strings

Author: chennes

technical/translation.md

@@ -11,7 +11,13 @@ In most cases, any user-visible text in FreeCAD should be made translatable. Exc
 2. Names of Python commands, etc.
 
 Some general guidelines when constructing strings for translation:
-* Not all languages use the same word order, so it's best to write complete sentences (and sometimes complete paragraphs), using the `QString::args()` function, or the Python `format()` function to do replacements where necessary.
+* Not all languages use the same word order, so developers should write complete phrases/sentences (and sometimes complete paragraphs), using the `QString::args()` function, or the Python `format()` function to do replacements where necessary. For example, use `tr("Edit the %1 using the %2").args(varOne).args(varTwo)` instead of `tr("Edit the ") + varOne + tr(" using the ") + varTwo`.
+* Avoid using Rich Text or HTML for labels unless their formatting capabilities are absolutely necessary.
+* Do not abbreviate unless absolutely necessary for space considerations. For example "Boolean operation", not "Bool Op".
+* Use capital letters for Workbench names, and lowercase elsewhere, to help disambiguate. For example "Create a Path object" refers to the Path workbench, but "Create a part" referes to a conceptual "part".
+* Never rely on the displayed string as a conditional value in your code: you must always map from your internal representation to a translatable string. For example, if a `QComboBox` is constructed with a set of user options, you should only ever examine the *index* of the current item, and never its actual displayed text.
+
+Important technical details:
 * The NOOP-versions of the Qt translation functions extract the string for translation purposes, but *do not* replace the string in place with its translated equivalent. A later call to `tr()` or `translate()` is always required in these cases. See more detail below.
 * In a non-QObject-derived class, use `Q_DECLARE_TR_FUNCTIONS(MyClass)` to give your class access to the `tr()` function. See also [the Qt documentation](https://doc.qt.io/qt-5/i18n-source-translation.html).