locale.hxx

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2012 Thorsten Brehm - brehmt (at) gmail com
// SPDX-License-Identifier: GPL-2.0-or-later

 
#ifndef __FGLOCALE_HXX
#define __FGLOCALE_HXX
 
#include <cstdarg> // for va_start/_end
#include <memory>
#include <string>
#include <vector>
 
#include <simgear/props/propsfwd.hxx>
#include <simgear/misc/strutils.hxx>
 
#include <Translations/TranslationDomain.hxx>
 
// forward decls
class SGPath;
 
namespace flightgear {
    class FGTranslate;
    class TranslationDomain;
};
 
namespace simgear { class Dir; }
 

// FGLocale  //////////////////////////////////////////////////////////////////
 
/******************************************************************************
 * Main concepts: default translation vs. other translations, etc.
 *
 * The “default translation” is made of all source strings found in the
 * XML files present in $FG_ROOT/Translations/default/ and its
 * `auto-extracted` subdirectory (also in aircraft and add-ons with the
 * aircraft or add-on base directory substituted for $FG_ROOT). This
 * translation does not correspond to any of the /sim/intl/locale[n] nodes.
 *
 * The default translation has only one form for any given string: the “source
 * text” (this is what translators translate). Each of its strings is loaded
 * in the _sourceText member of the corresponding TranslationUnit instance.
 * Therefore, it can't have variations like singular and plural forms. It
 * should use indeterminate style like “Here are %1 apple(s)”. Its language is
 * referred to here as “engineering English”.
 *
 * Other translations are proper ones, that can have different forms depending
 * on an integer that is optionally passed to the API functions
 * (cf. FGTranslate::setCardinalNumber()). These translations are all loaded
 * from XLIFF files in Translations/⟨language dir⟩ where ⟨language dir⟩ is not
 * 'default' (for aircraft and add-ons, use the most specific variant for
 * ⟨language dir⟩, e.g. 'fr_FR' as opposed to just 'fr': this will allow
 * correct selection of the locale node according to locale.xml). In such
 * translations, each _sourceText of a TranslationUnit instance has:
 *
 *   - no translation if the string hasn't been translated yet (an empty
 *     'target' text in the .xlf file counts as “no translation”);
 *
 *   - exactly one translation (_targetTexts[0] in the TranslationUnit) if the
 *     string has has-plural="false" or no such attribute in the default
 *     translation;
 *
 *   - a language-dependent number of translations that can be obtained by
 *     passing the “language id” (cf. locale.xml) to
 *     LanguageInfo::getNumberOfPluralForms() (these translations are loaded
 *     into the _targetTexts vector of TranslationUnit instances);
 *
 * Language selection
 * ------------------
 *
 * When fgfs is started with --language=default, it uses the default
 * translation (“engineering English”). This is normally only useful for
 * debugging. In this case, FGLocale::selectLanguage() sets _currentLocale to
 * the empty shared pointer. In all other cases, FGLocale::selectLanguage()
 * chooses one of the /sim/intl/locale[n] nodes according to --language, the
 * user-level and system-level language settings, and the
 * /sim/intl/locale[n]/lang nodes defined in locale.xml (if no match is found,
 * it uses the “fallback locale” which corresponds to /sim/intl/locale[0] and
 * is proper English with plural forms). This results in one XLIFF file to be
 * loaded if present (also for the current aircraft and for registered
 * add-ons).
 *
 * When FGLocale::selectLanguage() returns and FlightGear uses the default
 * locale:
 *
 *   - _currentLocale is the empty shared pointer;
 *   - _languageId is the "default" string;
 *   - FlightGear did not and won't load any XLIFF file.
 *
 * When FGLocale::selectLanguage() returns and FlightGear does not use the
 * default locale:
 *
 *   - _currentLocale points to the /sim/intl/locale[n] node corresponding to
 *      the selected language;
 *   - _languageId is the string value of /sim/intl/locale[n]/language-id;
 *   - FlightGear loaded one XLIFF file indicated by
 *     /sim/intl/locale[n]/core/xliff (unless none was there: abnormal
 *     situation), and will possibly load more later from the current
 *     aircraft and add-ons.
 *
 * FGLocale::selectLanguage() sets /sim/intl/current-locale to the value of
 * _currentLocaleString and /sim/intl/current-language-id to the value of
 * _languageId. The latter determines which XLIFF files are going to be
 * loaded, if any. Therefore, if a font has to be chosen according to the
 * selected language, getLanguageId() or /sim/intl/current-language-id should
 * be appropriate.
 *
 * Resource vs. context
 * --------------------
 *
 * Both terms mean essentially the same thing here. A resource can more easily
 * be considered as something that _contains_ translation material, however
 * when these terms refer to a single string parameter, they mean the same
 * thing: the resource name such as “atc”, “menu”, “options”, “sys”, “tips”,
 * etc.
 ******************************************************************************/
 
class FGLocale
{
public:
    FGLocale(SGPropertyNode* root);
    virtual ~FGLocale();

    bool selectLanguage(const std::string& language = {});
    std::string getLanguageId() const;

    std::string getPreferredLanguage() const;
 
    void loadAircraftTranslations();
    void loadAddonTranslations();

    std::string getLocalizedStringWithIndex(const std::string& id,
                                            const std::string& context,
                                            int index) const;
    std::string getLocalizedString(const std::string& id,
                                   const std::string& resource,
                                   const std::string& defaultValue = {});

    std::vector<std::string> getLocalizedStrings(const std::string& id,
                                                 const std::string& resource);

    std::size_t getLocalizedStringCount(const std::string& id,
                                        const std::string& context) const;

    std::string getDefaultFont      (const char* fallbackFont);

    std::string localizedPrintf(const char* id, const char* resource, ... );
    
    std::string vlocalizedPrintf(const char* id, const char* resource, va_list args);
    
    static void utf8toLatin1        (std::string& s);

    void clear();

    SGPropertyNode_ptr selectLanguageNode(SGPropertyNode* langs) const;
 
protected:
    SGPropertyNode* findLocaleNode(const std::string& language);

    void loadResourceForDefaultTranslation(
        const SGPath& xmlFile, const std::string& domain,
        const std::string& resource);
    void loadDefaultTranslation(const simgear::Dir& defaultTranslationDir,
                                const std::string& domain);
    void loadCoreResourcesForDefaultTranslation();

    void loadResourcesFromAircraftOrAddonDir(const SGPath& basePath,
                                             const std::string& domain);
    void loadXLIFFFromAircraftOrAddonDir(const SGPath& basePath,
                                         const std::string& domain);
    string_list getUserLanguages() const;
    std::string findLanguageId() const;
 
    SGPropertyNode_ptr _intl;
    SGPropertyNode_ptr _currentLocale;
    std::string _languageId;
    SGPropertyNode_ptr _fallbackLocale;
    std::string _currentLocaleString;

    void loadXLIFF(const SGPath& basePath, SGPropertyNode* localeNode,
                   const std::string& domain);
private:
    static std::string removeEncodingPart(const std::string& locale);
    std::shared_ptr<const flightgear::TranslationDomain> getDomain(
        const std::string& domain) const;
 
    // this is the ordered list of languages to try. It's the same as
    // returned by getUserLanguages(), except if the user has used
    // --language to override, that will be the first item.
 
    string_list _languages;
    bool _inited = false;
 
    // Keys are domain names such as "core", "addons/⟨addonId⟩", etc.
    using TranslationDomainRef = std::shared_ptr<flightgear::TranslationDomain>;
    std::map<std::string, TranslationDomainRef> _domains;
 
    // FGTranslate uses our getDomain(), which is private.
    friend class FGTranslate;
};
 
// global translation wrappers
 
std::string fgTrMsg(const char* key);
std::string fgTrPrintfMsg(const char* key, ...);
 
 
#endif // __FGLOCALE_HXX