Create translation.md

Author: chennes

technical/translation.md

@@ -0,0 +1,66 @@
+---
+layout: default
+---
+#  Writing Code for Translation
+
+How to write code with strings that should be translated
+
+In most cases, any user-visible text in FreeCAD should be made translatable. Exceptions to this general rule are:
+1. Text that only appears as log-level messages in the Report View
+2. Names of Workbenches (e.g. "Start", "Part", "Path")
+3. 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 `Qtring::args()` function, or the Python `format()` function to do replacements where necessary.
+* The script that extracts translatable strings from Python does not currently (as of Qt 6.4) support Python string concatenation, so to follow the above guideline you *must* write your translatable string on a single line of code.
+* 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. They should generally only be used in classes derived from Gui::Command for things like the menu entry and tooltip. The Command class handles actually loading the translated string.
+* 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).
+
+## Translating plurals
+
+Many languages have complex pluralization rules. To support this, you can write strings that are designed for pluralization, including in English, by specifying a parameter that indicates how many of a thing there are. The translation system will dynamically select the correct translation (assuming translators wrote one), even for English. For example
+```
+int nErrors = getNumberOfErrors(); // Might be zero, might be one, might be some other number.
+tr("There were %n errors.", "", nErrors);
+```
+Translators will be given the opportunity to translate this string in several variants (depending on the language they are translating for). For example, in English we would have:
+```
+There were 0 errors.
+There was 1 error.
+There were 2 errors.
+```
+In other languages there might be more than two variants, the sentence structure might change completely, etc. Qt and the CrowdIn translation platform support this structure.
+
+## Testing your strings
+
+The translation process has several steps, each of which you can examine during the development process.
+
+### String extraction
+
+To determine whether your strings are being correctly extracted, you can directly run the `lupdate` command on the file you are working on, using a dummy TS output file. `lupdate` is included in your Qt installation (note that internally we use lupdate from Qt 6.4 -- this is particularly important if you are testing Python code, as several major problems were address by a patch we submitted to Qt 6.4).
+```
+lupdate MySourceCodeFile.cpp --ts test.ts
+```
+will generate the file test.ts -- you can examine it to ensure your string appears with the expected context in that file. In particular, make sure that each string makes sense alone: otherwise, without context, translators will not know what they should replace it with.
+
+### String replacement
+
+To determine whether the string is being replaced correctly, you can create a dummy language file from the above test.ts file, and inject it into your FreeCAD instance. To do this you must know the name of the file that the finished translations will be put into. In general this is the name of the module you are working on, an underscore, the language code, and ".ts". For example, "PartDesign_es-ES.ts" is the Spanish (Spain) translation file for the Part Design workbench. An exception is the code in `src/Gui`, which is FreeCAD_xx.ts (where xx is the language code). 
+
+For testing purposes, choose a language you are familiar with (or at least, can navigate well enough to deactivate when you are done testing!), and copy the file generated by lupdate into the appropriate filename. Locate the string you want to test:
+```
+    <message>
+        <location filename="../CommandDoc.cpp" line="1649"/>
+        <source>Activates or Deactivates the selected object&apos;s edit mode</source>
+        <translation type="unfinished"></translation>
+    </message>
+```
+Edit this to eliminate the "unfinished" and to add a translation, e.g.
+```
+    <message>
+      <location filename="../CommandDoc.cpp" line="1649"/>
+      <source>Activates or Deactivates the selected object's edit mode</source>
+      <translation>Activa o desactiva el modo de edición del objeto seleccionado</translation>
+    </message>
+```
+Next, this file must be converted to a `*.qm` file using the `lrelease` tool (distributed with Qt). Finally, place the generated QM file in the same location as your user.cfg file, in a subdirectory called "translations", then switch FreeCAD to the language you chose to test with. Your translated string should appear.