Локализация и интернационализация с 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. Вы даже можете иметь строки пользовательского интерфейса в 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.