pip/libs/main/application/pitranslator.h

//! \~\file pitranslator.h
//! \~\ingroup Application
//! \brief
//! \~english Translation support
//! \~russian Поддержка перевода
/*
    PIP - Platform Independent Primitives
    Translation support
    Ivan Pelipenko peri4ko@yandex.ru

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU Lesser General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

#ifndef pitranslator_H
#define pitranslator_H

#include "pistring.h"


#ifdef DOXYGEN

//! \relatesalso PITranslator
//! \~\brief
//! \~english Alias to \a PITranslator::tr().
//! \~russian Алиас к \a PITranslator::tr().
#  define piTr

//! \relatesalso PITranslator
//! \~\brief
//! \~english Alias to \a PITranslator::trNoOp().
//! \~russian Алиас к \a PITranslator::trNoOp().
#  define piTrNoOp

#else

#  define piTr     PITranslator::tr
#  define piTrNoOp PITranslator::trNoOp

#endif

//! \~\ingroup Application
//! \~\brief
//! \~english Translation support
//! \~russian Поддержка перевода
//! \~\details
//! \~english Provides translation support with context-aware string wrappers and multiple loading methods.
//! %PITranslator stores loaded translations in a process-wide singleton.
//! If translation or context is missing, the source string is returned unchanged.
//! \~russian Предоставляет поддержку перевода с контекстно-зависимыми обертками строк и методами загрузки.
//! %PITranslator хранит загруженные переводы в синглтоне процесса.
//! Если перевод или контекст не найдены, исходная строка возвращается без изменений.
class PIP_EXPORT PITranslator {
public:
	//! \~english Returns translated string for "in" in optional "context".
	//! \~russian Возвращает перевод строки "in" в необязательном "context".
	static PIString tr(const PIString & in, const PIString & context = {});

	//! \~english Converts UTF-8 string literal to %PIString and translates it.
	//! \~russian Преобразует UTF-8 строковый литерал в %PIString и переводит его.
	static PIString tr(const char * in, const PIString & context = {}) { return tr(PIString::fromUTF8(in), context); }

	//! \~english Marks string for translation-aware code paths and returns it unchanged.
	//! \~russian Помечает строку для кода, работающего с переводом, и возвращает ее без изменений.
	static PIString trNoOp(const PIString & in, const PIString & context = {}) { return in; }

	//! \~english UTF-8 overload of \a trNoOp().
	//! \~russian UTF-8 перегрузка для \a trNoOp().
	static PIString trNoOp(const char * in, const PIString & context = {}) { return trNoOp(PIString::fromUTF8(in), context); }

	//! \~english Clears all loaded translations.
	//! \~russian Очищает все загруженные переводы.
	static void clear();

	//! \~english Clears current translations and loads language files matching "short_lang" from "dir".
	//! \~russian Очищает текущие переводы и загружает языковые файлы, соответствующие "short_lang", из "dir".
	static void loadLang(const PIString & short_lang, PIString dir = {});

	//! \~english Loads translations from textual configuration content.
	//! \~russian Загружает переводы из текстового конфигурационного содержимого.
	static void loadConfig(const PIString & content);

	//! \~english Loads translations from binary content in PIP translation format.
	//! \~russian Загружает переводы из бинарного содержимого в формате переводов PIP.
	static bool load(const PIByteArray & content);

	//! \~english Loads translations from file and checks its translation header.
	//! \~russian Загружает переводы из файла и проверяет его заголовок переводов.
	static bool loadFile(const PIString & path);

private:
	PITranslator();
	~PITranslator();
	NO_COPY_CLASS(PITranslator)
	PRIVATE_DECLARATION(PIP_EXPORT)

	static PITranslator * instance();
};

#ifndef PIP_HAS_FILESYSTEM
// no-filesystem build: translations cannot be loaded from disk, all strings pass through unchanged
inline PIString PITranslator::tr(const PIString & in, const PIString &) {
	return in;
}
inline void PITranslator::clear() {}
inline void PITranslator::loadLang(const PIString &, PIString) {}
inline void PITranslator::loadConfig(const PIString &) {}
inline bool PITranslator::load(const PIByteArray &) {
	return false;
}
inline bool PITranslator::loadFile(const PIString &) {
	return false;
}
#endif // PIP_HAS_FILESYSTEM


//! \~\ingroup Application
//! \~\brief
//! \~english Context-aware string wrapper that automatically translates strings using PITranslator::tr().
//! Helper returned by \a operator""_tr for optional-context translation.
//! \~russian Контекстно-зависимая обертка строки, автоматически переводящая строки с помощью PITranslator::tr().
//! Вспомогательный тип, возвращаемый \a operator""_tr для перевода с необязательным контекстом.
class PIStringContextTr {
public:
	//! \~english Stores source string for later translation.
	//! \~russian Сохраняет исходную строку для последующего перевода.
	PIStringContextTr(PIString && s): _s(s) {}

	//! \~english Translates stored string without explicit context.
	//! \~russian Переводит сохраненную строку без явного контекста.
	operator PIString() const { return PITranslator::tr(_s); }

	//! \~english Translates stored string in context "ctx".
	//! \~russian Переводит сохраненную строку в контексте "ctx".
	PIString operator()(const PIString & ctx = {}) const { return PITranslator::tr(_s, ctx); }

private:
	PIString _s;
};


//! \~\ingroup Application
//! \~\brief
//! \~english Context-aware string wrapper that preserves original strings without translation (no-op).
//! Helper returned by \a operator""_trNoOp that keeps source text unchanged.
//! \~russian Контекстно-зависимая обертка строки, сохраняющая оригинальные строки без перевода (заглушка).
//! Вспомогательный тип, возвращаемый \a operator""_trNoOp, который сохраняет исходный текст без изменений.
class PIStringContextTrNoOp {
public:
	//! \~english Stores source string without translating it.
	//! \~russian Сохраняет исходную строку без перевода.
	PIStringContextTrNoOp(PIString && s): _s(s) {}

	//! \~english Returns stored string unchanged.
	//! \~russian Возвращает сохраненную строку без изменений.
	operator PIString() const { return _s; }

	//! \~english Returns stored string unchanged and ignores "ctx".
	//! \~russian Возвращает сохраненную строку без изменений и игнорирует "ctx".
	PIString operator()(const PIString & ctx = {}) const { return _s; }

private:
	PIString _s;
};


//! \~\brief
//! \~english User-defined literal that defers translation through \a PITranslator::tr().
//! \~russian Пользовательский литерал, откладывающий перевод через \a PITranslator::tr().
//! \~\code "hello"_tr \endcode
inline PIStringContextTr operator""_tr(const char * v, size_t sz) {
	return PIStringContextTr(PIString::fromUTF8(v, sz));
}

//! \~\brief
//! \~english User-defined literal that keeps source text unchanged via \a PITranslator::trNoOp().
//! \~russian Пользовательский литерал, сохраняющий исходный текст без изменений через \a PITranslator::trNoOp().
//! \~\code "hello"_trNoOp \endcode
inline PIStringContextTrNoOp operator""_trNoOp(const char * v, size_t sz) {
	return PIStringContextTrNoOp(PIString::fromUTF8(v, sz));
}

#endif