Класс QTranslator

Класс QTranslator обеспечивает поддержку локализации для вывода текста. Подробнее...

• Список всех членов, включая наследуемые

Открытые функции

• 32 открытых функций, унаследованных от QObject

Дополнительные наследуемые члены

• 1 свойство, унаследованное от QObject
• 1 открытый слот, унаследованный от QObject
• 2 сигнала, унаследованные от QObject
• 11 статических открытых членов, унаследованных от QObject
• 9 защищённых функций, унаследованных от QObject

Подробное описание

Класс QTranslator обеспечивает поддержку локализации для вывода текста.

Объект этого класса содержит набор переводов из исходного языка на целевой язык. QTranslator предоставляет функции для поиска переводов в файле перевода. Файлы перевода создаются с помощью Qt Linguist.

Наиболее распространенное использование QTranslator заключается в следующем: загрузить файл перевода, установить его с помощью QCoreApplication::installTranslator() и использовать его через QObject::tr(). Вот пример main() функции, использующей QTranslator:

int main(int argc, char *argv[])
{
    QApplication app(argc, argv);

    QTranslator translator;
    // look up e.g. :/translations/myapp_de.qm
    if (translator.load(QLocale(), QLatin1String("myapp"), QLatin1String("_"), QLatin1String(":/translations")))
        app.installTranslator(&translator);

    QPushButton hello(QCoreApplication::translate("main", "Hello world!"));
    hello.resize(100, 30);

    hello.show();
    return app.exec();
}

Обратите внимание, что переводчик должен быть создан до создания виджетов приложения.

Большинству приложений не нужно будет делать ничего другого с этим классом. Другие функции, предоставляемые этим классом, полезны для приложений, работающих с файлами перевода.

Поиск переводов

Можно найти перевод, используя translate() (как tr() и QCoreApplication::translate()). Функция translate() принимает до трех параметров:

• context — обычно имя класса для вызывающего tr().
• source text — обычно аргумент для tr().
• disambiguation — необязательная строка, которая помогает избежать неоднозначности при использовании одного и того же текста в одном и том же контексте.

Например, «Отмена» в диалоговом окне может иметь «Anuluj» при запуске программы на польском языке (в этом случае исходный текст будет «Cancel»). Контекстом обычно является имя класса диалогового окна; обычно комментарий отсутствует, а переведённый текст будет «Anuluj».

Но это не всегда так просто. В испанской версии диалогового окна принтера с параметрами двусторонней печати и брошюровки, вероятно, потребуются как «Activado», так и «Activada» в качестве переводов для «Enabled». В этом случае исходный текст будет «Enabled» в обоих случаях, а контекстом будет имя класса диалогового окна, но для двух элементов будут указаны различия, такие как «двусторонняя печать» для одного и «брошюровка» для другого. Различия позволяют переводчику выбрать подходящий род для испанской версии и позволяют Qt различать переводы.

Использование нескольких переводов

В приложении можно установить несколько файлов перевода. Переводы ищутся в обратном порядке, в котором они были установлены, поэтому файл перевода, установленный последним, ищется в первую очередь, а самый ранний файл перевода ищется последним. Поиск прекращается, как только находится перевод, содержащий соответствующую строку.

Этот механизм позволяет «выбирать» или предоставлять приоритет определенному переводу над другими; просто удалите переводчик из приложения, передав его функции QCoreApplication::removeTranslator(), и повторно установите его с помощью QCoreApplication::installTranslator(). Тогда этот перевод будет первым, который будет проверен на соответствие строк.

См. также QCoreApplication::installTranslator(), QCoreApplication::removeTranslator(), QObject::tr(), QCoreApplication::translate(), Пример I18N, Пример Hello tr(), Пример Arrow Pad и Пример Troll Print.

Документация по членам функций

QTranslator::QTranslator(QObject *parent = Q_NULLPTR)

Создаёт пустой объект файла сообщений с родителем parent, который не подключен к какому-либо файлу.

QTranslator::~QTranslator()

Удаляет объект и освобождает все выделенные ресурсы.

[virtual] bool QTranslator::isEmpty() const

Возвращает true если этот переводчик пуст, в противном случае возвращает false. Эта функция работает с укороченными и неукороченными файлами перевода.

bool QTranslator::load(const QString &filename, const QString &directory = QString(), const QString &search_delimiters = QString(), const QString &suffix = QString())

Загружает filename + suffix (".qm", если suffix не указан), что может быть полным именем файла или относительным к directory. Возвращает true если перевод успешно загружен; в противном случае возвращает false.

Если directory не указан, используется текущая директория (т. е. как currentPath()).

Предыдущее содержимое объекта переводчика отбрасывается.

Если имя файла не существует, пробуются другие имена файлов в следующем порядке:

1. Имя файла без добавленного suffix.
2. Имя файла со строкой после символа в search_delimiters удалена ("_." по умолчанию для search_delimiters, если это пустая строка) и suffix.
3. Имя файла без добавленного suffix.
4. Имя файла без дальнейшего обрезания, и т.д.

Например, приложение, работающее в локали fr_CA (франкоязычная Канада), может вызвать load("foo.fr_ca", "/opt/foolib"). load() затем попытается открыть первый существующий читаемый файл из этого списка:

1. /opt/foolib/foo.fr_ca.qm
2. /opt/foolib/foo.fr_ca
3. /opt/foolib/foo.fr.qm
4. /opt/foolib/foo.fr
5. /opt/foolib/foo.qm
6. /opt/foolib/foo

Обычно лучше использовать функцию QTranslator::load(const QLocale &, const QString &, const QString &, const QString &, const QString &), потому что она использует QLocale::uiLanguages() и не просто имя локали, которое относится к форматированию дат и чисел, а не обязательно к языку пользовательского интерфейса.

bool QTranslator::load(const QLocale &locale, const QString &filename, const QString &prefix = QString(), const QString &directory = QString(), const QString &suffix = QString())

Загружает filename + prefix + имя языка UI + suffix (".qm", если suffix не указан), что может быть полным именем файла или относительным к directory. Возвращает true если перевод успешно загружен; в противном случае возвращает false.

Предыдущее содержимое объекта переводчика отбрасывается.

Если имя файла не существует, пробуются другие имена файлов в следующем порядке:

1. Имя файла без прикрепленного суффикса.
2. Имя файла с частью языка интерфейса после символа "_" и удалённым суффиксом.
3. Имя файла с удалённой частью языка интерфейса без прикреплённого суффикса.
4. Имя файла с дальнейшим удалением части языка интерфейса и т.д.

Например, приложение, работающее в языковом окружении с указанными ниже языками интерфейса - "es", "fr-CA", "de" может вызвать load(QLocale(), "foo", ".", "/opt/foolib", ".qm"). load() заменит '-' (дефис) на '_' (подчеркивание) в языке интерфейса и затем попытается открыть первый существующий читаемый файл из этого списка:

1. /opt/foolib/foo.es.qm
2. /opt/foolib/foo.es
3. /opt/foolib/foo.fr_CA.qm
4. /opt/foolib/foo.fr_CA
5. /opt/foolib/foo.de.qm
6. /opt/foolib/foo.de
7. /opt/foolib/foo.fr.qm
8. /opt/foolib/foo.fr
9. /opt/foolib/foo.qm
10. /opt/foolib/foo.
11. /opt/foolib/foo

В операционных системах, где файловая система чувствительна к регистру, QTranslator также пытается загрузить версию имени локали в нижнем регистре.

Эта функция была введена в Qt 4.8.

bool QTranslator::load(const uchar *data, int len, const QString &directory = QString())

Эта функция перегружает load().

Загружает данные файла QM data длиной len в переводчик.

Данные не копируются. Вызывающая сторона должна гарантировать, что data не будет удалён или изменён.

directory используется только для указания базового каталога при загрузке зависимостей файла QM. Если у файла нет зависимостей, этот аргумент игнорируется.

[virtual] QString QTranslator::translate(const char *context, const char *sourceText, const char *disambiguation = Q_NULLPTR, int n = -1) const

Возвращает перевод для ключа (context, sourceText, disambiguation). Если не найдено, также пытается (context, sourceText, ""). Если это всё ещё не удалось, возвращает пустую строку.

Примечание: Неполные переводы могут привести к неожиданному поведению: Если перевод для (context, sourceText, "") не предоставлен, метод в этом случае может фактически вернуть перевод для другого disambiguation.

Если n не равно -1, оно используется для выбора подходящей формы перевода (например, «найден файл %n» против «найдено файлов %n»).

Если вам нужно программно вставлять переводы в QTranslator, эту функцию можно переопределить.

См. также load().