gettext
индексирует или/и переводит некоторые индексированные сообщения на английском языке
Синтаксис
gettext("The literal reference message") gettext(["item #1" ; "item#2"]) translated = gettext("The literal reference message") translated = gettext(["item #1" ; "item#2"]) translated = gettext(msgid) .. gettext(domain, ..)
Аргументы
- "The literal reference message"
Единый с учетом регистра символьный текст сообщения на английском языке, которое требуется индексировать или/и перевести. Может быть также указан столбец символьных текстов явно разделённых точкой с запятой. Messages can include some C-like placeholders starting with "%".
Могут использоваться только стандартные символы ASCII. Любые иные расширенные символы ASCII или UTF-8 приведут к ошибке в работеgettext()
.- msgid
одиночный идентификатор или массив идентификаторов сообщений с учетом регистра (на английском) для перевода, в переменной.
Могут использоваться только стандартные символы ASCII.- translated
Сообщения на входе переводятся на текущий язык сессии Scilab. Если для входного сообщения не доступна версия перевода, то возвращается входная версия на английском. Входные и выходные массивы имеют одинаковые размеры.
Эти сообщения определены в файлах ./locales/*.po. Они могут включать в себя расширенные символы ASCII или UTF-8.- domain
слово или текст: имя домена. При локализации внешнего модуля
domain
обычно может быть установлен на техническое имя модуля.domain
может быть как литералом, так и переменной. Он нечувствителен к регистру.domain
требуется вtbx_generate_pofile()
для того, чтобы сделать индексированную литеральную строкуmsgid
(этап сбора. См. ниже.).Когда
gettext(domain, msgid)
используется для получения переведённой версии, тоdomain
используется для получения пути к директории, где хранятся переводы, как это заранее записано с помощьюaddlocalizationdomain(domain, path)
.
Описание
Сбор сообщений и общая обработка
gettext является свободным и открытым внешним приложением, поставляемым вместе с Scilab для поддержки мультилингвизма для сообщений. Эта поддержка состоит из 4 главных этапов:
Сбор сообщений внутри кода и индексирование их для перевода. Для внешнего модуля это явным образом выполняется с помощью внешней бинарной программы
xgettext
, которая является частью внешнего приложенияgettext
, и которая вызывается Scilab-функцией tbx_generate_pofile. В Scilab также можно использоватьtbx_build_localization(..)
илиtbx_make . localization
, которые обе вызываютtbx_generate_pofile(..)
.Каждое собранное сообщение рассматривается в качестве идентификатора (msgid) для всех его последующих переводов. В Scilab опорным языком для идентификаторов является английский. Следовательно идентификаторы сообщений для индексации должны быть записаны на английском.
В качестве входного аргумента
gettext
собираются только одиночные литеральные сообщения и сообщения одним куском. Таким образом, некоторые из следующих синтаксисов и случаев не будут индексировать рассматриваемое сообщение, и для них не будут доступны дополнительные переведенные версии:# Синтаксис Статус Результаты сбора 1 gettext("To be translated")
OK стандартный синтаксис 2 msg = "To be translated"; gettext(msg)
NOK Текст внутри переменной. Он не символьный. Он не будет индексирован. Тем не менее, этот синтаксис будет работать для получения версии перевода, в случае, если сообщение было собрано где-нибудь правильным образом. 3 gettext("To be" + " translated")
NOK "To be" и " translated" индексируются как 2 отдельных msgid
. Тогда, следовательно, конкатенированногоmsgid
"To be translated" не существует, получение его перевода не удастся.4 gettext("To be" + .. " translated")
NOK Также как и #3 5 gettext(["item#1", "item#2"])
NOK Только "item#1" собирается. "item#2" игнорируется. 6 gettext(["item#1" "item#2"])
NOK "item#1item#2" индексируется. Тогда, поскольку "item#1" и "item#2" неизвестные отдельные msgid
, то получение их соответствующего перевода не удастся.7 gettext(["item#1" "item#2"])
NOK Также как и #6 8 gettext(["item#1" ; "item#2"])
OK "item#1" и "item#2" индексируются в качестве отдельных msgid
.9 gettext(["item#1" ; "item#2"])
OK Также как и #8. Обратите внимание на точку с запятой. Без неё это будет случай ошибки #7. 10 // gettext("item") /* gettext("item #2") */ /* gettext("item #3") */
OK расположения gettext() в комментариях также индексируются. Для внешнего модуля tbx_generate_pofile() собирает только то, что встречаетgettext
с указанием доменаdomain
. Он игнорирует любой вызовgettext
только с одним входным аргументом.Сбору не нужно предварительно указывать домен
domain
вaddlocalizationdomain()
Все индексированные тексты затем переводятся автором кода или помощниками. В любом случае кем-то из людей. Хорошие инструменты перевода также доступны онлайн.
Все переведённые версии собираются таким образом, что
gettext(..)
становится эффективным для получения версии на текущем языке сессии. Это сделано запускомtbx_generate_pofile()
в другой раз.Наконец, некоторые вызовы, такие как
gettext(message)
илиgettext("The message content")
, используются для получения и выдачи переведённой версии.Когда сообщение не является естественным для Scilab (например, оно специфично для внешнего модуля), домен
domain
где сообщения и его переводы могут быть найдены, должен быть определён, как вgettext(domain, message)
илиgettext(domain, "The message content")
. В это случаеaddlocalizationdomain(domain, path)
должен быть запущен первым для того, чтобы указать Scilab директорию, в которой хранятся переведённые сообщения указанного доменаdomain
.
Чаще всего сообщения указываются для сбора и используются для получения их
переведённых версий через одинаковый вызов gettext("The literal message")
.
Однако, это не обязательно. Следовательно, кусок кода, такой как
if %F, gettext("The literal message"), end
никогда не
будет исполнен вызов gettext
, но тем не менее имеет
смысл: оно здесь только для того, чтобы сделать сообщение видимым для
сканера/сборщика xgettext
. Тогда где-то ещё в коде
можно использовать
msg = "The literal message"; gettext(msg)
для возврата
переведённой версии.
Также многократное использование одного и того же литерального вызова
gettext("The literal message")
не будет редким, например,
для получения перевода в нескольких файлах. В этом случае сборщик
xgettext
будет собирать сообщение только один раз,
и одинаковый перевод будет получен во всех вызовах.
Ограничения: Нет способа перевести сообщение
|
msgid сообщения
Для корректной обработки сообщения на английском должны соответствовать нескольким правилам:
Идентификаторы сообщений не чувствительны к регистру.
Литеральные собираемые сообщения могут быть разделены одиночными или двойными кавычками.
Когдаgettext()
или_()
используется в XML или XSL файлах, таких, как файлы настроек внешнего модуля, литеральная строка домена и литеральный идентификатор сообщения более не должны быть разделены. Например,_(my_domain, My message)
будет использоваться вместо_("my_domain", "My message")
.К тому же, пробелы до и после идентификатора сообщений тогда никогда не будут приниматься во внимание и никогда не будет принадлежать сообщению. Например, фактический идентификатор сообщения, соответствующий
_(my_domain, My message: )
это"My message:"
, а не" My message: "
.Двойные кавычки следует избегать внутри тела сообщения. Пожалуйста, используйте одинарные кавычки.
Внутренние эскейп-последовательности, такие как "\t", "\n" и т.д., не интерпретируются ни сканером
xgettext
ни функциейgettext
. Они собираются и сохраняются как есть в сообщениях.Некоторые шаблонные сообщения могут часто включать в себя некоторые C-подобные директивы "%" с целью замены некоторыми входными данными через
msprintf()
во время запуска. Например,msprintf("Hi %s, could you come at %s today?", "John", "12:30")
вернёт"Hi John, could you come at 12:30 today?"
.
переведённые сообщения msgstr
Этот раздел будет в основном полезен тем, кто занимается переводом сообщений.
Special characters and sequences:
- When a trailing \n is used in the
msgid
, it must also end themsgstr
translated message. - ' single quotes are regular characters in
msgstr
strings. They do NOT need any special care or protection. - " double quotes must be protected with \".
- When some C-like placeholders like %s, %d, %f, or some C-like escaped
sequences \n, \r, or \t are used in the
msgid
string, this means that later in the code the correspondingtranslated
msgstr
string is processed withmsprintf()
to replace placeholders with actual values, and/or to interpret \n as a new_line character, \r as a carriage-return, \t as a tabulation, etc. Hence, all the C-like printf rules apply on the consideredmsgstr
, and translaters must take a major care to them.- All and Only the placeholders used in the
msgid
must also appear in themsgstr
. - If placeholders are not numbered: they must appear in the same order
in the
translated
msgstr
message than in themsgid
message. Example (english to french):msgid "%s is %d year old.\n" msgstr "%s a %d ans.\n" // первый %s (строка), второй %d (десятичное число), в обоих строках. Затем из Scilab-сессии установим французский язык и тогда получим gettext("%s is %d year old.\n") // => "%s a %d ans.\n" // и первый v v второй t = msprintf(gettext("%s is %d year old.\n"), "Peter", 18) // => "Peter a 18 ans."
В противном случае, ВСЕ заменители должны быть пронумерованы в переведённом сообщении
translated
. Каждый пронумерованный заменитель может быть использован только один раз в формате (ограничение Scilab). Например (с английского на японский):msgid "%s: Wrong number of input argument: %d to %d expected.\n" msgstr "%1$s: 入力引数で不正な数: %3$d への %2$d を想定します。\n" Тогда, msprintf(gettext("%s: Wrong number of input argument: %d to %d expected.\n"), "myFun", 2, 5) вернёт в Scilab-сессию, установленную на английский "myFun: Wrong number of input argument: 2 to 5 expected." а в Scilab-сессии, установленной на японский "myFun: 入力引数で不正な数: 5 への 2 を想定します。"
- All and Only the placeholders used in the
- \n, \r, \t sequences fortuitously appearing
in a
msgid
ending with "\n" should be considered as prone to issues, due to a lack of care from the programmer. This can occur for instance when some literal paths are part of themsgid
, like inmsgid "Please use the file C:\users\you\net\record\time.txt instead.\n"
The trailing\n
suggests that the correspondingmsgstr
will be processed bymsprintf()
or so. Being done,\n
in\net
,\r
in\record
and\t
in\time.txt
will be also -- unexpectedly -- interpreted. These\
will have to be protected in themsgstr
, even in the reference version (often english):msgstr "Please use the file C:\users\you\\net\\record\\time.txt instead.\n"
:
Примеры
setlanguage("fr"); // Идентификаторы сообщений чувствительны к регистру: // "monday" не является индексируемым msgid, в отличие от "Monday": gettext(["monday" ; "Monday"]) //_() является псевдонимом gettext(): _("Sunday") // В Scilab идентификаторы сообщений английские: setlanguage("ru"); _("Dimanche") // Французская версия не может использоваться в качестве msgid _("Sunday")
--> gettext(["monday" ; "Monday"]) ans = !monday ! !Lundi ! --> _("Sunday") ans = Dimanche --> setlanguage("ru"); --> _("Dimanche") ans = Dimanche --> _("Sunday") ans = Воскресенье
Использование домена: Здесь "tbx" это предопределённый домен, используемый для проверки возможности перевода:
setlanguage("fr"); msg = "%s: something not in Scilab.\n"; // неизвестный в главном домене для Scilab: gettext(msg) // поэтому он выдаётся как есть. // Если мы используем домен без предварительного его декларирования, то // Scilab не знает ещё где найти перевод: gettext("tbx", msg) // входное сообщение возвращается как есть. // Теперь задекларируем домен: addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale"); gettext("tbx", msg) // теперь работает // Ответом является шутка: здесь она остаётся на английском (хотя ожидалась на французском). // Дело в том, что она была установлена как французский перевод входного msgid. // Тот же msgid может использоваться в качестве идентификатора, естественного для Scilab с его переводами, // и в одном или в нескольких доменах с другими переводами: msg = "%s: No more memory.\n"; [_(msg) ; _("tbx", msg)]
--> msg = "%s: something not in Scilab.\n"; // неизвестный в главном домене для Scilab: --> gettext(msg) ans = %s: something not in Scilab.\n --> // Scilab не знает ещё где найти перевод: --> gettext("tbx", msg) ans = %s: something not in Scilab.\n --> // Теперь задекларируем домен: --> addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale"); --> gettext("tbx", msg) // теперь работает ans = %s : it is true, that is not in Scilab.\n --> msg = "%s: No more memory.\n"; --> [_(msg) ; _("tbx", msg)] ans = !%s : Plus de mémoire disponible.\n ! !%s : Overwrite Scilab translation.\n !
Сообщения с нумерованными C-подобными заменителями:
in = getlanguage(); msg = "%s: Unknown value %s for %s option"; // has already some translations setlanguage("en"); t = gettext(msg) msprintf(t, "setdiff", "''f''", "''direction''") setlanguage("ja"); t = gettext(msg) msprintf(t, "setdiff", "''f''", "''direction''") setlanguage(in);
--> setlanguage("en"); --> t = gettext(msg) t = "%s: Unknown value %s for %s option" --> msprintf(t, "setdiff", "''f''", "''direction''") ans = "setdiff: Unknown value 'f' for 'direction' option" --> setlanguage("ja"); --> t = gettext(msg) t = "%1$s: %3$s オプション の未知の値 %2$s" --> msprintf(t, "setdiff", "''f''", "''direction''") ans = "setdiff: 'direction' オプション の未知の値 'f'"
Смотрите также
- msprintf — converts, formats, and writes data in a string
- setlanguage — chooses the language used for standard messages and help pages for the current session
- addlocalizationdomain — add a new domain in localization mechanism.
- tbx_generate_pofile — Extracts gettext msgid strings from the toolbox source files. Creates/updates .po files
- tbx_make . localization — Builds fully or some given sections of a toolbox having a standard structure
- tbx_build_localization — Builds or updates localization .po and .mo files of a toolbox
- GNU gettext website
История
Версия | Описание |
5.5.0 | Добавлено управление доменом. |
6.1.0 | Теперь C-подобные заменители в сообщениях могут быть нумерованными. |
Report an issue | ||
<< getlanguage | Локализация | setdefaultlanguage >> |