Сбор сообщений и общая обработка

gettext является свободным и открытым внешним приложением, поставляемым вместе с Scilab для поддержки мультилингвизма для сообщений. Эта поддержка состоит из 4 главных этапов:

1. Сбор сообщений внутри кода и индексирование их для перевода. Для внешнего модуля это явным образом выполняется с помощью внешней бинарной программы 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.

   Для внешнего модуля tbx_generate_pofile() собирает только то, что встречает gettext с указанием домена domain. Он игнорирует любой вызов gettext только с одним входным аргументом. Сбору не нужно предварительно указывать домен domain в addlocalizationdomain()

2. Все индексированные тексты затем переводятся автором кода или помощниками. В любом случае кем-то из людей. Хорошие инструменты перевода также доступны онлайн.

3. Все переведённые версии собираются таким образом, что gettext(..) становится эффективным для получения версии на текущем языке сессии. Это сделано запуском tbx_generate_pofile() в другой раз.

4. Наконец, некоторые вызовы, такие как 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 будет собирать сообщение только один раз, и одинаковый перевод будет получен во всех вызовах.

Ограничения: Нет способа перевести сообщение на языке, отличном от языка текущей сессии. Если это действительно требуется, то язык сессии следует временно переключить на желаемый язык, затем вызвать gettext(), и, наконец, восстановить язык сессии. из переведённой версии, а не из идентификатора сообщения на английском.

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 translated messages

This section will be more useful for translaters than for actual users.

When an english msgid message includes some C-like placeholders, this always means that in the code the translated message is processed with msprintf() to replace placeholders with actual values. Hence, the order and type of placeholders indicate the order and types of actual input values when calling msprintf.

This is of first importance for translaters, when writing the corresponding translated message:

• If placeholders are not numbered: they must be in the same order and types in the translated msgstr message than in the msgid message. Example (english to french):

  msgid  "%s is %d year old.\n"
  msgstr "%s a %d ans.\n"
  // first %s (a string), second %d (a decimal number), in both strings.
  
  Then, from a Scilab session set to french, we will get
  gettext("%s is %d year old.\n") // => "%s a %d ans.\n"
  // and                                     first v      v second
  t = msprintf(gettext("%s is %d year old.\n"), "Peter", 18)
  // => "Peter a 18 ans."
  

• Otherwise, All placeholders must be numbered in the translated message. Each numbered placeholder can be used only once in the format (Scilab limitation). Example (english to japanese):

  msgid "%s: Wrong number of input argument: %d to %d expected.\n"
  msgstr "%1$s: 入力引数で不正な数: %3$d への %2$d を想定します。\n"
  
  Then,
  msprintf(gettext("%s: Wrong number of input argument: %d to %d expected.\n"), "myFun", 2, 5)
  
  will return in a Scilab session set to english
  "myFun: Wrong number of input argument: 2 to 5 expected."
  
  while, in a Scilab session set to japanese
  "myFun: 入力引数で不正な数: 5 への 2 を想定します。"