Локализация и международная поддержка с Qt Quick

Локализация вашего приложения

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

1. Используйте qsTr() для всех текстовых строк пользовательского интерфейса

Строки в QML можно пометить для перевода с помощью функций qsTr(), qsTranslate(), qsTrId(), QT_TR_NOOP(), QT_TRANSLATE_NOOP(), и QT_TRID_NOOP(). Наиболее распространенный способ маркировки строк — функция qsTr(). Например:

Text {
    id: txt1;
    text: qsTr("Back");
}

Этот код добавляет «Назад» в качестве ключевого элемента в файлы перевода. Во время выполнения система перевода ищет ключевое слово «Назад» и получает соответствующее значение перевода для текущего системного региона. Результат возвращается в свойство text и пользовательский интерфейс отобразит соответствующий перевод «Назад» для текущего региона.

2. Добавление контекста для переводчика

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

Примечание: Файлы .ts являются XML-файлами с исходным текстом и местом для переведенного текста. Обновленные файлы .ts преобразуются в двоичные файлы перевода и включаются в окончательное приложение.

В следующем фрагменте кода текст на строке //: является основным комментарием для переводчика.

Текст на строке //~ — это необязательная дополнительная информация. Первое слово текста используется в качестве дополнительного идентификатора в XML-элементе в файле .ts, поэтому убедитесь, что первое слово не является частью предложения. Например, комментарий «Контекст не связан с этим» преобразуется в «<extra-Context>Не связан с этим» в файле .ts.

Text {
    id: txt1;
    // This user interface string is only used here
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back");
}

3. Различение идентичных текстов

Система перевода объединяет строки текста пользовательского интерфейса в уникальные элементы. Это объединение экономит время переводчику, так как ему не нужно переводить один и тот же текст несколько раз. Однако в некоторых случаях текст идентичен, но имеет разный смысл. Например, в английском языке «back» может означать «назад» (шаг назад) и «задняя часть» (противоположная передней части объекта). Необходимо сообщить системе перевода об этих двух различных значениях, чтобы переводчик смог создать два отдельных перевода.

Различайте идентичные тексты, добавив некоторый идентификатор в качестве второго параметра функции qsTr().

В следующем фрагменте кода текст not front является идентификатором для различения этого текста «Назад» от текста «Назад» для шага назад:

Text {
    id: txt1;
    // This user interface string is used only here
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back", "not front");
}

4. Используйте %x для вставки параметров в строку

Разные языки имеют различный порядок слов, поэтому не следует создавать предложения путем конкатенации слов и данных. Вместо этого используйте % для вставки параметров в строки. Например, следующий фрагмент содержит строку с двумя числовыми параметрами %1 и %2. Эти параметры вставляются с помощью функций .arg().

Text {
    text: qsTr("File %1 of %2").arg(counter).arg(total)
}

%1 относится к первому параметру, а %2 — ко второму параметру, поэтому этот код генерирует вывод типа: «Файл 2 из 3».

5. Используйте %Lx для локализации чисел

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

Text {
    text: qsTr("%L1").arg(total)
}

Затем, если total — это число «4321.56» (четыре тысячи триста двадцать один целых пятьдесят шесть сотых); с английскими региональными настройками (регионом) вывод будет «4,321.56»; с немецкими региональными настройками — «4.321,56».

6. Локализация дат, времени и валют

Нет специальных модификаторов строк для форматирования дат и времени. Вместо этого необходимо запросить текущий регион и использовать методы класса Date для форматирования строки.

Qt.locale() возвращает объект Locale, содержащий всю информацию о регионе. В частности, свойство Locale.name содержит информацию о языке и стране для текущего региона. Вы можете использовать значение как есть или проанализировать его для определения соответствующего содержимого для текущего региона.

Следующий фрагмент получает текущую дату и время с помощью Date(), затем преобразует ее в строку для текущего региона. Затем он вставляет строку даты в параметр %1 для соответствующего перевода.

Text {
    text: qsTr("Date %1").arg(Date().toLocaleString(Qt.locale()))
}

Для локализации числовых значений валют используйте тип Number. Этот тип имеет функции, аналогичные типу Date, для преобразования чисел в локализованные строки валюты.

7. Используйте QT_TR_NOOP() для текстовых строк данных, подлежащих переводу

Если пользователь меняет язык системы без перезагрузки, в зависимости от системы, строки в массивах, моделях списков и других структурах данных могут не обновляться автоматически. Чтобы принудительно обновить тексты при их отображении в пользовательском интерфейсе, необходимо объявить строки с помощью макроса QT_TR_NOOP(). Затем, при заполнении объектов для отображения, необходимо явно получить перевод для каждого текста. Например:

ListModel {
    id: myListModel;
    ListElement {
        //: Capital city of Finland
        name: QT_TR_NOOP("Helsinki");
        }
    }

...

Text {
    text: qsTr(myListModel.get(0).name); // get the translation of the name property in element 0
    }

8. Используйте регион для расширения функций локализации

Если вы хотите использовать различные графические или аудиоэлементы для разных регионов, вы можете использовать Qt.locale() для получения текущего региона. Затем вы выбираете соответствующие графические или аудиоэлементы для этого региона.

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

Component.onCompleted: {
    switch (Qt.locale().name.substring(0,2)) {
        case "en":   // show the English-language icon
            languageIcon = "../images/language-icon_en.png";
            break;
        case "fi":   // show the Finnish language icon
            languageIcon = "../images/language-icon_fi.png";
            break;
        default:     // show a default language icon
            languageIcon = "../images/language-icon_default.png";
    }
}

9. Подготовка к динамическим изменениям языка

Вы можете изменить язык, используемый функциями перевода Qt, добавив и удалив переводчиков с помощью QCoreApplication::installTranslator() и QCoreApplication::removeTranslator(). После этого вы можете вызвать QQmlEngine::retranslate() для запуска обновления всех связей, использующих переводы. В результате ваш пользовательский интерфейс динамически переключится на вновь выбранный язык.

В качестве альтернативы вы также можете переслать событие QEvent::LanguageChange в экземпляр QQmlEngine вашего приложения или подключить свой собственный сигнал к QQmlEngine::retranslate().

Локализация вашего приложения

Приложения Qt Quick используют ту же базовую систему локализации, что и приложения Qt C++ (lupdate, lrelease и файлы .ts). Вы используете те же инструменты, что и описаны в руководстве Qt Linguist Manual. Вы даже можете иметь строки пользовательского интерфейса в C++ и QML-источнике в одном приложении. Система создаст единый объединенный файл перевода, и к строкам можно будет получить доступ из QML и C++.

Использование условия для скрытия QML-источника от компилятора

Инструмент lupdate извлекает строки пользовательского интерфейса из вашего приложения. lupdate считывает файл .pro вашего приложения, чтобы определить, какие исходные файлы содержат тексты, подлежащие переводу. Это означает, что ваши исходные файлы должны быть перечислены в записи SOURCES или HEADERS в файле .pro. Если ваши файлы не указаны, тексты в них не будут найдены.

Однако переменная SOURCES предназначена для файлов исходного кода C++. Если вы перечислите QML или JavaScript-файлы исходного кода, компилятор попытается создать их как C++-файлы. В качестве обходного решения можно использовать условное выражение lupdate_only{...}, чтобы инструмент lupdate видел файлы .qml, но C++-компилятор их игнорировал.

Например, следующий фрагмент файла .pro определяет два файла .qml в приложении.

lupdate_only{
SOURCES = main.qml \
          MainPage.qml
}

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

lupdate_only{
SOURCES = *.qml \
          *.js \
          content/*.qml \
          content/*.js
}

Дополнительные сведения о локализации Qt см. в руководстве Qt Linguist Manual.