LlmQtLocaleLanguageManager is an utilitarian class that simplifies language choice management in a multilingual Qt application. More...

#include <LlmQtLocaleLanguageManager.h>

Public Member Functions
bool	analyseAvailableLanguages (QString *sReturnErrMsg=nullptr)
	Analyse which are the available languages/translations for the application. More...

QString	currentLanguageNativeName ()
	Return the name of the current language, in native form. More...

bool	isSystemLanguageAvailable ()
	Indicate if one of the system languages is available among the qm files. More...

bool	isSystemLanguageChosenByUser ()
	Indicate if the Language choice is "System language". More...

bool	isUsable ()
	Indicate if the class is usable. More...

QStringList	languageNameNativeList (bool bIntegrateSystemLanguageFlag)
	List of the available languages, in native form. More...

	LlmQtLocaleLanguageManager (const LlmQtLocaleLanguageManager &)=delete

LlmQtLocaleLanguageManager &	operator= (const LlmQtLocaleLanguageManager &)=delete

void	setKeySettingsTranslateLanguage (const QString &sKey)
	Modify the key to access "Locale-language" value in user's settings. More...

void	setQmFilesDirectory (const QString &sQmFilesDirectory)
	Set qm files directory. More...

void	setSettings (const std::shared_ptr< QSettings > &settings)
	Set a user QSettings object to the language manager class (Use of that feature is optional). More...

bool	setSourceLanguage (QLocale::Language languageQtFlag, QLocale::Country countryQtFlag=QLocale::AnyCountry, QString *sReturnErrMsg=nullptr)
	Set the source's/primary languages informations. More...

void	setSourceLanguageFromQAppLocalSettings ()
	Guess source's interface language, from the default QLocal's values. More...

QString	sourceLanguageNativeName ()
	The native name of the interface (dialog panels) language used in sources. More...

QString	systemLanguageNativeName ()
	Return the name of the available system language name, in this native form (available among qm files). More...

bool	translateAppToLanguage (const QString &sLanguageNativeOrEnglishNameWithCountry, QString *sReturnErrMsg=nullptr)
	Translate the application to the the chosen language. More...

bool	translateAppToSystemLanguage (QString *sReturnErrMsg=nullptr)
	Translate the application to an available system language. More...

bool	translateAppToUserSettingsLanguage (QString *sReturnErrMsg=nullptr)
	Translate the application to the language indicated in the settings m_settings, under the language key. More...

Detailed Description

LlmQtLocaleLanguageManager is an utilitarian class that simplifies language choice management in a multilingual Qt application.

It provide methods to deal with .qm files, app's active language, system language, language switch, choice storing in user settings... It handle all the possible error during .qm files analysis. Dialog's straight translation at running time is possible.

How to use explanations and use examples are in main folder's README.md .

Author: Jon Petrissans

Member Function Documentation

bool LlmQtLocaleLanguageManager::analyseAvailableLanguages ( QString * sReturnErrMsg = nullptr )

Analyse which are the available languages/translations for the application.

The analysis is done according the .qm files found under m_qmFilesDirectory. LlmQtLocaleLanguageManager::setQmFilesDirectory() has to be called before. If .qm file is added/removed during running time, this method update the analysis.

Also, it look to the system languages, and if our app is translatable to a system language, that language is stored in m_systemLanguage.

In case of error, the method has 2 behaviours:

if sReturnErrMsg is used sReturnErrMsg return error's description, there is no exception throw.
if sReturnErrMsg is not used, the method throws an exception.

Parameters

[out] sReturnErrMsg Description of error

Returns: True if analysis is a success

Exceptions

runtime_error

Exceptions are raised only if sReturnErrMsg is not used. Throws an exception if:

qmFilesDirectory doesn't exist.
No qm file found.
LlmQtLocaleLanguageManager::languagePropertiesOfQmFile() throws an exception.

QString LlmQtLocaleLanguageManager::currentLanguageNativeName ( )

Return the name of the current language, in native form.

Returns: Name of the current language, in native form

bool LlmQtLocaleLanguageManager::isSystemLanguageAvailable ( )

Indicate if one of the system languages is available among the qm files.

An analysis need to be done before calling this method, with LlmQtLocaleLanguageManager::analyseAvailableLanguages().

Returns: True if one of the system languages is available.

bool LlmQtLocaleLanguageManager::isSystemLanguageChosenByUser ( )

Indicate if the Language choice is "System language".

Returns: True if the Language choice is "System language"

bool LlmQtLocaleLanguageManager::isUsable ( )

Indicate if the class is usable.

= qm files available + source language known.

Returns: True if LlmQtLocaleLanguageManager is usable

QStringList LlmQtLocaleLanguageManager::languageNameNativeList ( bool bIntegrateSystemLanguageFlag )

List of the available languages, in native form.

The list include the source language, and a SYSTEM flag if asked (and if the system language's translation is available). If a language has a country specification, the language name will be: "language name (Country code)".

Parameters

[in] bIntegrateSystemLanguageFlag Indicate if a SYSTEM flag is needed in the returned list.

Returns: List of the available languages.

void LlmQtLocaleLanguageManager::setKeySettingsTranslateLanguage ( const QString & sKey )

Modify the key to access "Locale-language" value in user's settings.

If not set, the default key is "Locale/Language"

Parameters

[in] sKey The new key

void LlmQtLocaleLanguageManager::setQmFilesDirectory ( const QString & sQmFilesDirectory )

Set qm files directory.

Parameters

sQmFilesDirectory Full path

void LlmQtLocaleLanguageManager::setSettings ( const std::shared_ptr< QSettings > & settings )

Set a user QSettings object to the language manager class (Use of that feature is optional).

If set, that QSettings object will be used to store the chosen languages. If not set, the language changes are just not saved, without any warning.

Parameters

[in] settings Settings object to be used

bool LlmQtLocaleLanguageManager::setSourceLanguage	(	QLocale::Language	languageQtFlag,
		QLocale::Country	countryQtFlag = `QLocale::AnyCountry`,
		QString *	sReturnErrMsg = `nullptr`
	)

Set the source's/primary languages informations.

The method is an alternative to LlmQtLocaleLanguageManager::setSourceLanguageFromQAppLocalSettings(), and is a better solution. This method is more "precise", and has to be privileged. It permit to set countryQtFlag to QLocale::AnyCountry.

Parameters

[in]	languageQtFlag	Languages Qt flag, from the QLocale::Language enum
[in]	countryQtFlag	Country Qt flag, from the QLocale::Country enum
[out]	sReturnErrMsg	description of error

Returns: True if success

Exceptions

runtime_error Exceptions are raised only if sReturnErrMsg is not used. Throws an exception if the language/country couple is not compatible.

void LlmQtLocaleLanguageManager::setSourceLanguageFromQAppLocalSettings ( )

Guess source's interface language, from the default QLocal's values.

The method is an alternative to LlmQtLocaleLanguageManager::setSourceLanguage(), but prefer use LlmQtLocaleLanguageManager::setSourceLanguage() instead of that one.

QString LlmQtLocaleLanguageManager::sourceLanguageNativeName ( )

The native name of the interface (dialog panels) language used in sources.

Returns: the native name of the source/primary interface language.

QString LlmQtLocaleLanguageManager::systemLanguageNativeName ( )

Return the name of the available system language name, in this native form (available among qm files).

An analysis need to be done before calling this method, with LlmQtLocaleLanguageManager::analyseAvailableLanguages().

Returns: The name of the available system language name, in this native form

bool LlmQtLocaleLanguageManager::translateAppToLanguage	(	const QString &	sLanguageNativeOrEnglishNameWithCountry,
		QString *	sReturnErrMsg = `nullptr`
	)

Translate the application to the the chosen language.

The default QLocale is also modified according the new language. The language name can be either in it's Native form or in it's English form (Français or French), it doesn't matter. It can contain the country code in brackets. (as given by LlmQtLocaleLanguageManager::languageNameNativeList()).

If a QSetting has been set, (thanks to LlmQtLocaleLanguageManager::setSettings() ), saves the changes in user's settings.

In case of error, the method has 2 behaviours:

if sReturnErrMsg is used sReturnErrMsg return error's description, there is no exception throw
if sReturnErrMsg is not used, the method throws an exception

Parameters

[in]	sLanguageNativeOrEnglishNameWithCountry	The wanted language name in this Native form or in this English form (Français or French).
[out]	sReturnErrMsg	description of error

Returns: True is success

Exceptions

runtime_error

Exceptions are raised only if sReturnErrMsg is not used. Throws an exception if:

System language is asked and not available. (Use LlmQtLocaleLanguageManager::isSystemLanguageAvailable() to have that information).
Qm file load error.
Qm file of the asked language doesn't exist.

bool LlmQtLocaleLanguageManager::translateAppToSystemLanguage ( QString * sReturnErrMsg = nullptr )

Translate the application to an available system language.

(Available among the qm files) Before using that method, make sure a system language translation is available thanks LlmQtLocaleLanguageManager::isSystemLanguageAvailable(). If a QSetting has been set, (thanks to LlmQtLocaleLanguageManager::setSettings() ), saves the changes in user's settings.

In case of error, the method has 2 behaviours:

if sReturnErrMsg is used sReturnErrMsg return error's description, there is no exception throw.

if sReturnErrMsg is not used, the method throws an exception.

Parameters

[out] sReturnErrMsg description of error

Returns: True if success

Exceptions

runtime_error

Exceptions are raised only if sReturnErrMsg is not used. Throws an exception if :

The translation to the system language is not available. System language availability can be checked with LlmQtLocaleLanguageManager::isSystemLanguageChosen()
LlmQtLocaleLanguageManager::translateAppToLanguage throws an exception

bool LlmQtLocaleLanguageManager::translateAppToUserSettingsLanguage ( QString * sReturnErrMsg = nullptr )

Translate the application to the language indicated in the settings m_settings, under the language key.

The key is indicated thanks to LlmQtLocaleLanguageManager::setKeySettingsTranslateLanguage(). A QSetting has to be set first, thanks to LlmQtLocaleLanguageManager::setSettings().

In case of error, the method has 2 behaviours:

if sReturnErrMsg is used sReturnErrMsg return error's description, there is no exception throw
if sReturnErrMsg is not used, the method throws an exception
Parameters

[out] sReturnErrMsg description of error

Returns
True if success

Exceptions

runtime_error Exceptions are raised only if sReturnErrMsg is not used. Throws an exception if:
LlmQtLocaleLanguageManager::translateAppToLanguage() throws an exception.
QSetting has not been set.

The documentation for this class was generated from the following files:

LlmQtLocaleLanguageManager.h
LlmQtLocaleLanguageManager.cpp

Public Member Functions

Detailed Description

Member Function Documentation