Класс 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, удалённый ("_." по умолчанию для 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 + имя языка пользовательского интерфейса + 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 также пытается загрузить версию имени locale в нижнем регистре.

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, ""). Если это тоже не удалось, возвращает пустую строку.

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

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

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