Написание исходного кода для перевода

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

Использование QString для всего отображаемого пользователю текста

Поскольку QString использует кодировку Unicode внутри, любой язык мира может обрабатываться прозрачно с помощью знакомых операций обработки текста. Кроме того, так как все функции Qt, отображающие текст пользователю, принимают QString в качестве параметра, нет необходимости в преобразовании из char * в QString, что исключает накладные расходы.

Строки, находящиеся в «пространстве программиста» (например, имена QObject и тексты форматов файлов), не должны использовать QString; подойдут традиционные char * или класс QByteArray.

Вы вряд ли заметите, что используете Unicode; QString и QChar — просто более удобные версии грубых const char * и char из традиционного C.

char * строки в исходном коде предполагаются закодированными в UTF-8 при неявном преобразовании в QString. Если ваш строковый литерал C использует другую кодировку, используйте QString::fromLatin1() или QTextCodec для преобразования литерала в закодированный в Unicode QString.

Использование tr() для всего текстового литерала

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

Например, предположим, что LoginWidget является подклассом QWidget:

LoginWidget::LoginWidget()
{
    QLabel *label = new QLabel(tr("Password:"));
    ...
}

Это обеспечивает 99% отображаемых пользователю строк, которые вы, скорее всего, напишете.

Если текст в кавычках не находится в методе члена подкласса QObject, используйте либо функцию tr() соответствующего класса, либо функцию QCoreApplication::translate() непосредственно:

void some_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
                LoginWidget::tr("Password:"), logwid);
}

void same_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
                QCoreApplication::translate("LoginWidget", "Password:"), logwid);
}

Qt индексирует каждую переводимую строку по контексту перевода, с которым она связана; это, как правило, имя подкласса QObject.

Контексты перевода определяются для новых классов, основанных на QObject, с помощью макроса Q_OBJECT в каждом новом определении класса.

Когда вызывается tr(), она ищет переводимую строку с помощью объекта QTranslator. Для работы перевода один или несколько из них должны быть установлены на объект приложения таким образом, как описано в разделе Включение перевода.

Перевод строк в QML работает точно так же, как и в C++, за исключением того, что вам нужно вызвать qsTr() вместо tr(). См. также страницу о Локализации и интернационализации с Qt Quick.

Определение контекста перевода

Контекстом перевода для QObject и каждого подкласса QObject является само имя класса. Разработчики, создающие подклассы QObject, должны использовать макрос Q_OBJECT в своём определении класса для переопределения контекста перевода. Этот макрос устанавливает контекст в имя подкласса.

Например, следующее определение класса включает макрос Q_OBJECT, реализуя новый tr(), который использует MainWindow контекст:

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow();
    ...

Если Q_OBJECT не используется в определении класса, контекст будет унаследован от базового класса. Например, поскольку все классы, основанные на QObject в Qt, предоставляют контекст, новый подкласс QWidget, определённый без макроса Q_OBJECT, будет использовать QWidget контекст, если его функция tr() вызвана.

Использование tr() для получения перевода

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

void MainWindow::createMenus()
{
    fileMenu = menuBar()->addMenu(tr("&File"));
    ...

Здесь контекст перевода MainWindow, потому что именно функция MainWindow::tr() вызвана. Текст, возвращаемый функцией tr(), представляет собой перевод «&Файл», полученный из контекста MainWindow.

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

В некоторых ситуациях полезно явно указать контекст перевода, полностью квалифицируя вызов tr(); например:

QString text = QScrollBar::tr("Page up");

Этот вызов получает переведенный текст «Перейти на предыдущую страницу» из контекста QScrollBar. Разработчики также могут использовать функцию QCoreApplication::translate() для получения перевода для конкретного контекста перевода.

Использование tr() для локализации чисел

Вы можете локализовать числа, используя соответствующие строки tr():

void Clock::setTime(const QTime &time)
{
    if (tr("AMPM") == "AMPM") {
        // 12-hour clock
    } else {
        // 24-hour clock
    }
}

В примере для США мы оставим перевод «AMPM» без изменений и таким образом будем использовать 12-часовой формат времени; но в Европе мы переведём его по-другому, чтобы код использовал 24-часовой формат времени.

Перевод классов, не являющихся классами Qt

Иногда необходимо предоставить поддержку интернационализации для строк, используемых в классах, которые не наследуют QObject или не используют макрос Q_OBJECT для включения функций перевода. Поскольку Qt переводит строки во время выполнения на основе класса, к которому они относятся, и lupdate ищет переводимые строки в исходном коде, классы, не являющиеся классами Qt, должны использовать механизмы, которые также предоставляют эту информацию.

Один из способов сделать это — добавить поддержку перевода в класс, не являющийся классом Qt, с помощью макроса Q_DECLARE_TR_FUNCTIONS(); например:

class MyClass
{
    Q_DECLARE_TR_FUNCTIONS(MyClass)

public:
    MyClass();
    ...
};

Это предоставляет классу функции tr(), которые могут быть использованы для перевода строк, связанных с классом, и позволяет lupdate найти переводимые строки в исходном коде.

В качестве альтернативы можно вызвать функцию QCoreApplication::translate() со специфическим контекстом, и это будет распознано lupdate и Qt Linguist.

Комментарии для переводчика

Разработчики могут включать информацию о каждой переводимой строке, чтобы помочь переводчикам с процессом перевода. Эти данные извлекаются, когда lupdate используется для обработки исходных файлов. Рекомендуемый способ добавления комментариев — добавить аннотации к вызовам tr() в вашем коде в формате:

//: ...

или

/*: ... */

Примеры:

//: This name refers to a host name.
hostNameLabel->setText(tr("Name:"));

/*: This text refers to a C++ code example. */
QString example = tr("Example");

В этих примерах комментарии будут связаны со строками, переданными в tr(), в контексте каждого вызова.

Добавление метаданных к строкам

Дополнительные данные могут быть присоединены к каждому переводимому сообщению. Эти данные извлекаются, когда lupdate используется для обработки исходных файлов. Рекомендуемый способ добавления метаданных — добавить аннотации к вызовам tr() в вашем коде в формате:

//= <id>

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

Альтернативный способ добавления метаданных — использовать следующий синтаксис:

//~ <field name> <field contents>

Это можно использовать для добавления метаданных к сообщению. Имя поля должно состоять из префикса домена (возможно, традиционного расширения файла формата, на котором основано поле), дефиса и имени поля в формате с нижним подчёркиванием. Для хранения в файлах TS имя поля вместе с префиксом «extra-» сформирует имя XML-элемента. Содержимое поля будет экранировано XML, но в противном случае будет представлено дословно как содержимое элемента. Можно добавить любое количество уникальных полей к каждому сообщению.

Пример:

//: This is a comment for the translator.
//= qtn_foo_bar
//~ loc-layout_id foo_dialog
//~ loc-blank False
//~ magic-stuff This might mean something magic.
QString text = MyMagicClass::tr("Sim sala bim.");

Вы можете использовать ключевое слово TRANSLATOR для комментариев для переводчиков. Метаданные, стоящие прямо перед ключевым словом TRANSLATOR, применяются ко всему файлу TS.

Разрешение неоднозначности

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

Пример:

MyWindow::MyWindow()
{
    QLabel *senderLabel = new QLabel(tr("Name:"));
    QLabel *recipientLabel = new QLabel(tr("Name:", "recipient"));
    ...

В Qt 4.4 и более ранних версиях этот параметр разбиения неоднозначности был предпочтительным способом указания комментариев переводчикам.

Обработка множественного числа

Некоторые переводимые строки содержат места для значений целых чисел и должны переводиться по-разному в зависимости от используемых значений.

Для решения этой проблемы разработчики передают дополнительный целочисленный аргумент функции tr() и, как правило, используют специальную запись для множественного числа в каждой переводимой строке.

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

Пример:

int n = messages.count();
showMessage(tr("%n message(s) saved", "", n));

Таблица ниже показывает, какая строка возвращается в зависимости от активного перевода:

Этот подход более гибкий, чем традиционный, например:

n == 1 ? tr("%n message saved") : tr("%n messages saved")

поскольку он также работает с целевыми языками, имеющими несколько форм множественного числа (например, ирландский имеет специальную форму «двойственного числа», которая должна использоваться, когда n равно 2), и он правильно обрабатывает случай n == 0 для языков, таких как французский, которые требуют единственного числа.

Для обработки форм множественного числа на родном языке необходимо также загрузить файл перевода для этого языка. Инструмент lupdate имеет параметр командной строки -pluralonly, который позволяет создавать файлы TS, содержащие только записи с формами множественного числа.

См. статью Qt Quarterly Формы множественного числа в переводах для получения более подробной информации об этой проблеме.

Вместо %n, можно использовать %Ln, чтобы получить локализованное представление n. Преобразование использует локаль по умолчанию, установленную с помощью QLocale::setDefault(). (Если локаль по умолчанию не была указана, используется системная локаль.)

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

Перевод текста, находящегося за пределами подкласса QObject

Использование QCoreApplication::translate()

Если цитируемый текст не находится в методе члена подкласса QObject, используйте либо функцию tr() соответствующего класса, либо функцию QCoreApplication::translate() непосредственно:

void some_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
            LoginWidget::tr("Password:"), logwid);
}

void same_global_function(LoginWidget *logwid)
{
    QLabel *label = new QLabel(
            QCoreApplication::translate("LoginWidget", "Password:"),
            logwid);
}

Использование QT_TR_NOOP() и QT_TRANSLATE_NOOP() в C++

Если вам нужно иметь текст, подлежащий переводу, полностью вне функции, существуют два макроса, которые помогут: QT_TR_NOOP() и QT_TRANSLATE_NOOP(). Они просто помечают текст для извлечения инструментом lupdate. Макросы расширяются до простого текста (без контекста).

Пример использования QT_TR_NOOP():

QString FriendlyConversation::greeting(int type)
{
    static const char *greeting_strings[] = {
        QT_TR_NOOP("Hello"),
        QT_TR_NOOP("Goodbye")
    };
    return tr(greeting_strings[type]);
}

Пример использования QT_TRANSLATE_NOOP():

static const char *greeting_strings[] = {
    QT_TRANSLATE_NOOP("FriendlyConversation", "Hello"),
    QT_TRANSLATE_NOOP("FriendlyConversation", "Goodbye")
};

QString FriendlyConversation::greeting(int type)
{
    return tr(greeting_strings[type]);
}

QString global_greeting(int type)
{
    return QCoreApplication::translate("FriendlyConversation",
                                       greeting_strings[type]);
}

Если вы отключите автоматическое преобразование const char * в QString путем компиляции вашего программного обеспечения с определенным макросом QT_NO_CAST_FROM_ASCII, вы, скорее всего, обнаружите любые отсутствующие строки. См. QString::fromUtf8() и QString::fromLatin1() для получения дополнительной информации.

Использование QKeySequence() для значений акселератора

Значения акселераторов, такие как Ctrl+Q или Alt+F, также необходимо переводить. Если вы жестко закодируете Qt::CTRL + Qt::Key_Q для «выход» в своем приложении, переводчики не смогут его переопределить. Правильный способ:

exitAct = new QAction(tr("E&xit"), this);
exitAct->setShortcuts(QKeySequence::Quit);

Использование пронумерованных аргументов

Функции QString::arg() предлагают простой способ подстановки аргументов:

void FileCopier::showProgress(int done, int total,
                              const QString &currentFile)
{
    label.setText(tr("%1 of %2 files copied.\nCopying: %3")
                  .arg(done)
                  .arg(total)
                  .arg(currentFile));
}

В некоторых языках порядок аргументов может потребоваться изменить, и это легко достигается путем изменения порядка аргументов % . Например:

QString s1 = "%1 of %2 files copied. Copying: %3";
QString s2 = "Kopierer nu %3. Av totalt %2 filer er %1 kopiert.";

qDebug() << s1.arg(5).arg(10).arg("somefile.txt");
qDebug() << s2.arg(5).arg(10).arg("somefile.txt");

выводит правильный вывод на английском и норвежском языках:

5 of 10 files copied. Copying: somefile.txt
Kopierer nu somefile.txt. Av totalt 10 filer er 5 kopiert.

Дополнительная информация

Руководство по Qt Linguist, Пример Hello tr(), Правила перевода для множественного числа