.. SPDX-FileCopyrightText: 2026 Florent Rougon .. SPDX-License-Identifier: GPL-2.0-or-later .. Define the 'shell' role so that one can have syntax highlighting when using inline code as in :shell:`some-command argument...` cf. https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting .. role:: shell(code) :language: bash .. This allows one to use `...` instead of :shell:`...` in this document .. default-role:: shell .. _translation infrastructure: Translations ============ The Qt Workflow --------------- The :ref:`workflow ` for extracting translatable strings from FlightGear Qt C++ source code or QML files is rather standard and is entirely managed by the core development team. Scenery, aircraft or add-on developers normally don't need to bother with that. .. figure:: images/translation-workflows/Qt-workflow.* :figname: translations-Qt-workflow :class: dark-light :alt: Figure that shows how translatable strings are extracted from FlightGear assets processed by the Qt toolkit (for instance, all kinds of labels used by the built-in launcher). The Qt translation workflow Qt translatable strings are extracted from C++ and QML files by the Qt :program:`lupdate` tool. The result is written to :file:`fgdata/Translations/{lang}/FlightGear-Qt.xlf` files. The :program:`fg-fix-Qt-translation-files` program was used to fix problems in the ``FlightGear-Qt.xlf`` files generated by :program:`lupdate`. Now that we pass ``-disable-heuristic similartext`` to :program:`lupdate`, it seems that these problems don't occur anymore. The Non-Qt Workflow ------------------- The :ref:`workflow ` for extracting translatable strings from FlightGear code and assets that aren't managed by the Qt library is non-standard, because it needs to integrate with assets in FlightGear-specific formats such as XML description of GUI dialogs, other PropertyList files such as weather scenarios, and hopefully Nasal code in the future. It relies on Python scripts and modules located in the `fgmeta-python`_ repository that are shipped in the `flightgear Python package`_ (``fgmeta-python`` is the source repository of the package). The scripts and modules extract translatable strings from FlightGear assets and write the result to XLIFF files that have the :file:`.xlf` extension. `XLIFF `_ is a standard XML-based format; this allows translators to use nice existing tools such as `Qt Linguist`_ to update and review their translations. .. _fgmeta-python: https://gitlab.com/flightgear/fgmeta-python .. _flightgear Python package: https://pypi.org/project/FlightGear/ .. _XLIFF 1.2 spec: https://docs.oasis-open.org/xliff/v1.2/os/xliff-core.html .. _Qt Linguist: https://doc.qt.io/qt-6/qtlinguist-index.html .. figure:: images/translation-workflows/nonQt-workflow.* :figname: translations-nonQt-workflow :class: dark-light :alt: Figure that shows how translatable strings are extracted from FlightGear assets that are not (directly) processed by the Qt toolkit. The non-Qt translation workflow The translation scripts work on a directory hierarchy that has to be specified and corresponds to either FGData or an aircraft or add-on. The root directory of this hierarchy is noted :file:`{root}` here. .. todo:: The following explanations are probably too detailed for this place. In the simplest case, translatable strings are manually written to XML files in :file:`{root}/Translations/default/`. These can be readily found by scripts such as :program:`fg-update-translation-files` to update the XLIFF files (i.e., those that translators can work on and that FlightGear reads at startup). Other translatable strings are by necessity located outside :file:`{root}/Translations/` (labels of GUI dialogs, etc.). These have to be :dfn:`extracted` from their natural place to some location where :program:`fg-new-translations` and :program:`fg-update-translation-files` can find them. This is the job of the :program:`fg-extract-translatable-strings` script. It searches for XML files under the designated :file:`{root}` directory, extracts strings that are marked using the ```` processing instruction and writes the extracted strings to XML files in :file:`{root}/Translations/default/auto-extracted/`. These files mustn't be manually edited; every change to these files must be done by invoking :program:`fg-extract-translatable-strings`. This ensures that the extracted strings can always be mechanically derived from their sources (that is, the location where the strings are declared with ````). Whenever you add, delete or modify an extractable translatable string—for instance, in an XML dialog file—, you should run :program:`fg-extract-translatable-strings` and commit the resulting :file:`{root}/Translations/default/auto-extracted/*.xml` files *along with the modification.* If this shows more changes than what you did, it means someone most likely forgot to do so in a previous commit (i.e., source and extracted strings were already out-of-sync before your modification). When extracted strings are properly synchronized with their sources, the command `fg-extract-translatable-strings write /path/to/root` does not change any file. Thus, one typically runs this command followed by `git status` to make sure extracted strings are in sync with their sources.