Международная и локальная поддержка в 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";
    }
}

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

Приложения 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.