Международная и локальная локализация с 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" означает "назад" (шаг назад) и также означает "обратная" часть объекта по отношению к передней. Вам нужно сообщить системе перевода об этих двух отдельных значениях, чтобы переводчик мог создать два отдельных перевода.

Различайте идентичные тексты, добавив текст id в качестве второго параметра функции 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.