Класс QTranslator

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

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

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

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

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

Наиболее распространенное использование QTranslator: загрузить файл перевода и установить его с помощью QCoreApplication::installTranslator().

Вот пример main() функции, использующей QTranslator:

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

    QTranslator translator;
    // look up e.g. :/i18n/myapp_de.qm
    if (translator.load(QLocale(), QLatin1String("myapp"), QLatin1String("_"), QLatin1String(":/i18n")))
        QCoreApplication::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 = nullptr)

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

[virtual] QTranslator::~QTranslator()

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

[since 5.15] QString QTranslator::filePath() const

Возвращает путь к загруженному файлу перевода.

Путь к файлу пуст, если перевод еще не был загружен, загрузка не удалась или перевод не был загружен из файла.

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

[virtual] bool QTranslator::isEmpty() const

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

[since 5.15] QString QTranslator::language() const

Возвращает целевой язык, как хранится в файле перевода.

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

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 и добавленным suffix ("_." по умолчанию для search_delimiters, если это пустая строка).
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 + имя языка интерфейса + suffix (".qm", если suffix не указан), что может быть полным именем файла или относительным к directory. Возвращает true, если перевод успешно загружен; в противном случае возвращает false.

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

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

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

Например, приложение, работающее в locale с следующими языками интерфейса - "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.fr.qm
6. /opt/foolib/foo.fr
7. /opt/foolib/foo.de.qm
8. /opt/foolib/foo.de
9. /opt/foolib/foo.qm
10. /opt/foolib/foo.
11. /opt/foolib/foo

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

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 = nullptr, int n = -1) const

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

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

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

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

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