178 lines
8.2 KiB
C++
178 lines
8.2 KiB
C++
//! \~\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();
|
||
};
|
||
|
||
|
||
//! \~\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
|