Международная локализация и перевод с 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, предоставляемые переводчику.

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

Текст на строке //~ — это дополнительная необязательная информация. Первое слово текста используется в качестве дополнительного идентификатора в 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. Используйте %1, %2... для вставки параметров в строку

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

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

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

5. Используйте %Lx, чтобы числа были локализованы

Если вы используете модификатор %Lx при указании параметра, число локализуется в соответствии с текущими региональными настройками. Например, в следующем фрагменте кода %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. Вы даже можете иметь строки пользовательского интерфейса в 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 Linguist для получения дополнительной информации о локализации Qt.