Translation infrastructure
==========================

Important classes used to implement FlightGear translations are
:cpp:class:`FGLocale`, :cpp:class:`FGTranslate`,
:cpp:class:`TranslationDomain`, :cpp:class:`TranslationResource`,
:cpp:class:`TranslationUnit`. There are also two parser classes:
:cpp:class:`DefaultTranslationParser` and :cpp:class:`flightgear::XLIFFParser`.

Base concepts like translation domains and resources (the latter being also
known as translation *contexts*) are currently explained in `locale.hxx`_.

.. _locale.hxx: https://gitlab.com/flightgear/flightgear/-/blob/next/src/Main/locale.hxx

In order to obtain translations at runtime, :cpp:class:`FGTranslate` is a
convenient one-stop shop, however when fetching several strings from the same
resource, storing a reference to the appropriate
:cpp:class:`TranslationResource` and querying it repeatedly is better (less
wasteful). Ditto with :cpp:class:`TranslationDomain` when fetching
translations from the same domain, etc.

How to use these classes can be seen for instance `in the test suite`__.

.. __: https://gitlab.com/flightgear/flightgear/-/tree/next/test_suite/unit_tests/Translations?ref_type=heads

Some of the functions in :cpp:class:`FGLocale`, such as
:cpp:func:`FGLocale::getLocalizedString()` and friends, are very thin wrappers
around member functions of :cpp:class:`FGTranslate` that keep
previously-existing code working. Those in :cpp:class:`FGTranslate` and other
classes are more recent and likely more powerful (support for plural forms,
etc.).

.. toctree::
   :maxdepth: 2
   :caption: Classes

   classes/FGLocale
   classes/FGTranslate
   classes/TranslationDomain
   classes/TranslationResource
   classes/TranslationUnit
   classes/DefaultTranslationParser
   classes/XLIFFParser