Класс QTranslator

Класс 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(), Пример локализации, Пример Hello tr(), Пример Arrow Pad и Пример Troll Print.

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

QTranslator::QTranslator(QObject *parent = nullptr)

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

[virtual] 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. Имя файла без добавленного suffix.
2. Имя файла с частью языка UI после символа «_» удалённой и suffix.
3. Имя файла с частью языка UI удалённой без suffix.
4. Имя файла с ещё большей частью языка UI удалённой и т. д.

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

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. Если файл не имеет зависимостей, этот аргумент игнорируется.

QString QTranslator::translate(const char *context, const char *sourceText, const char *disambiguation = nullptr, int n = -1) const

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

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

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

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

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