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

Написание кроссплатформенного международного программного обеспечения с помощью 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 для преобразования литерала в QString в кодировке Unicode.

Использование 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(), Правила перевода для множественного числа