1 <?xml version="1.0" encoding="UTF-8"?>
3 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4 * Copyright (C) 2007 - INRIA - Allan CORNET
5 * Copyright (C) 2007 - INRIA - Sylvestre LEDRU
6 * Copyright (C) 2012 - 2016 - Scilab Enterprises
7 * Copyright (C) 2018 - Samuel GOUGEON
9 * This file is hereby licensed under the terms of the GNU GPL v2.0,
10 * pursuant to article 5.3.4 of the CeCILL v.2.1.
11 * This file was originally licensed under the terms of the CeCILL v2.1,
12 * and continues to be available under such terms.
13 * For more information, see the COPYING file which you should have received
14 * along with this program.
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18 xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
19 xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
20 xml:lang="en" xml:id="gettext">
22 <refname>gettext</refname>
23 <refpurpose>indexes or/and translates some indexed english messages</refpurpose>
25 <refnamediv xml:id="_">
34 gettext("The literal reference message")
35 gettext(["item #1" ; "item#2"])
36 translated = gettext("The literal reference message")
37 translated = gettext(["item #1" ; "item#2"])
38 translated = gettext(msgid)
39 .. gettext(domain, ..)
43 <title>Arguments</title>
46 <term>"The literal reference message"</term>
49 Single literal text of an english message to be indexed or/and
50 translated. A column of literal texts explicitly separated with
51 semi-colons may also be specified.
59 single or array of messages identifiers (in english) to be translated,
65 <term>translated</term>
68 Input messages translated in the current language of the Scilab session.
69 If no translated version is available for an input message, the input
70 version in english is returned. The input and output arrays have
79 word of text: the name of a domain. When localizing an external module,
80 <varname>domain</varname> may be usually set to the technical name of the
84 <varname>domain</varname> can indifferently be a literal or a variable.
88 <varname>domain</varname> is required by
89 <literal>tbx_generate_pofile()</literal> to make the literal msgid string
90 indexed (harvesting stage. See below).
93 When <literal>gettext(domain, msgid)</literal> is used to retrieve the
94 translated version, <varname>domain</varname> is used to get the path
95 to the directory where translations are stored, as beforehand registered
96 with <literal>addlocalizationdomain(domain, path)</literal>.
103 <title>Description</title>
105 <title>Harvesting messages and overall processing</title>
107 <emphasis role="italic">gettext</emphasis> is a free and open external application
108 shipped within Scilab to support multilinguism for messages. This support consists in
113 <emphasis role="bold">Harvesting</emphasis> messages among the code and
114 <emphasis role="bold">indexing</emphasis> them to be
115 translated. For an external module, this is explicitly performed with the
116 <literal>xgettext</literal> external binary, that is part of the
117 <literal>gettext</literal> external application, and that is called by the
118 <link linkend="tbx_generate_pofile">tbx_generate_pofile</link> Scilab function.
119 In Scilab, it is also possible to use <literal>tbx_build_localization(..)</literal>
120 or <literal>tbx_make . localization</literal>, that both call
121 <literal>tbx_generate_pofile(..)</literal>.
124 Each collected message is considered as an identifier (a message id, = msgid)
125 for all its forthcoming translations. In Scilab, the reference language for
126 identifiers is <emphasis role="italic">english</emphasis>.
127 Therefore, the msgids to be indexed must be written in english.
130 Only <emphasis role="bold">single literal and in one piece messages</emphasis>
131 being as <literal>gettext</literal> input argument are collected. Hence,
132 the following syntaxes and cases won't index the considered message, and no
133 further translated versions will be available:
138 <th>#</th><th>Syntax</th><th>Status</th>
139 <th align="left">Harvesting results</th>
143 <td style="white-space:nowrap">
144 <literal>gettext("To be translated")</literal>
147 <td>standard syntax</td>
151 <td style="white-space:pre"><screen><![CDATA[
152 msg = "To be translated";
153 gettext(msg)]]></screen>
157 The text is in a variable. It is not a literal.
159 Nevertheless, this syntax will work to <emphasis>retrieve</emphasis>
160 the translated version, <emphasis>provided that the message
161 has been collected elsewhere in a right way</emphasis>.
166 <td style="white-space:nowrap">
167 <literal>gettext("To be" + " translated")</literal>
171 "To be" and " translated" are indexed as 2 separate msgid.
172 Then, since the concatenated msgid "To be translated" does not exist,
173 retrieving its translation will fail.
178 <td style="white-space:pre"><screen><![CDATA[
180 " translated")]]></screen>
187 <td style="white-space:nowrap">
188 <literal>gettext(["item#1", "item#2"])</literal>
191 <td>Only "item#1" is collected. "item#2" is ignored.</td>
195 <td style="white-space:nowrap">
196 <literal>gettext(["item#1" "item#2"])</literal>
200 "item#1item#2" is indexed. Then, since "item#1" and "item#2"
201 are unknown separate msgid, retrieving their respective
202 translation will fail.
207 <td style="white-space:pre"><screen><![CDATA[
209 "item#2"])]]></screen>
216 <td style="white-space:nowrap">
217 <literal>gettext(["item#1" ; "item#2"])</literal>
220 <td>"item#1" and "item#2" are indexed as separate msgids.</td>
224 <td style="white-space:pre"><screen><![CDATA[
226 "item#2"])]]></screen>
230 Same as #8. Please take care of the semi-colon. Without it,
237 For an external module,
238 <link linkend="tbx_generate_pofile">tbx_generate_pofile()</link>
239 harvests only <literal>gettext</literal> occurrences that specify a
240 <varname>domain</varname>. It ignores any call to <literal>gettext</literal>
241 with only one input argument.
243 Harvesting does not need to beforehand declare the
244 <varname>domain</varname> with
245 <literal>addlocalizationdomain()</literal>
252 All indexed texts are then translated by the author of the code or by some
253 contributors. Anyway, by some humans. Good translation tools are also available
260 All translated versions are bundled in a way that <literal>gettext(..)</literal>
261 becomes efficient to retrieve the version in the current session's language.
262 This is done by running <literal>tbx_generate_pofile()</literal> another
269 Finally, some calls like <literal>gettext(message)</literal> or
270 <literal>gettext("The message content")</literal> are used to retrieve and
271 return the translated version.
274 When the message is not a native Scilab one (for instance it is specific
275 to an external module), the <varname>domain</varname> where the message
276 and its translations can be found must be specified, as in
277 <literal>gettext(domain, message)</literal>
278 or <literal>gettext(domain, "The message content")</literal>.
279 In this case, <literal>addlocalizationdomain(domain, path)</literal> must
280 be run before in order to make <varname>domain</varname> pointing to
281 the storage directory.
287 Most often, a message is declared to be harvested and is used to retrieve its
288 translated version through the same <literal>gettext("The literal message")</literal>
290 However, it is not mandatory. Hence, a piece of code like
291 <literal>if %F, gettext("The literal message"), end</literal> will never execute
292 the <literal>gettext</literal> call, but is nevertherless meaningfull: It is here only
293 to make the message visible to the <literal>xgettext</literal> scanner/harvester.
294 Then, somewhere else in the code, it will be possible to use
295 <literal>msg = "The literal message"; gettext(msg)</literal> to return the translated
299 As well, using several times the same literal
300 <literal>gettext("The literal message")</literal> call won't be rare, for example to
301 retrieve the translation in several files. In this case, the <literal>xgettext</literal>
302 harvester will collect the message only once, and the same translation will be returned
306 Limitations: There is no way to translate a message
310 in a language other than the current session's one. If this is really required,
311 the session's language will have to be temporarily switched to the desired
312 language, then <literal>gettext()</literal> called, and at last the initial
313 session's language restored.
318 from a translated version rather than from the message id in english.
324 <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
326 <title>Messages</title>
328 To be correctly processed, english messages must comply with a few rules:
332 Messages identifiers are case-sensitive.
337 Literal harvestable messages may be indifferently delimited with single
341 When <literal>gettext()</literal> or <literal>_()</literal> is used in
342 a XML or XSL file such as in the preferences files of an external module,
343 the literal domain string and the literal message id must no longer be
346 For instance, <literal>_(my_domain, My message)</literal>
347 will be used instead of <literal>_("my_domain", "My message")</literal>.
349 In addition, spaces before and after the messageID are then never
350 taken into account and never belong to the message. For example,
351 the actual message ID corresponding to
352 <literal>_(my_domain, My message: )</literal> is
353 <literal>"My message:"</literal>, not
354 <literal>" My message: "</literal>.
360 Double quotes must be avoided in the body of messages. Please use single quotes.
365 Inner escaped sequences like "\t" "\n" etc are not interpreted, neither by
366 the <literal>xgettext</literal> scanner nor by the <literal>gettext</literal>
367 function. They are collected and stored as is in the messages.
372 Some template messages may often include some "%" C-like directives
373 aiming to be replaced with some custom input data through
374 <literal>msprintf()</literal> at run time.
376 <literal>msprintf("Hi %s, could you come at %s today?", "John", "12:30")</literal>
377 will return <literal>"Hi John, could you come at 12:30 today?"</literal>.
381 Now, let's assume that you wish to make the template message translatable:
382 <literal>msg = _("Hi %s, could you come at %s today?")</literal>
383 and <literal>msprintf(msg, "John", "12:30")</literal>
384 will be used. However, the author or/and translaters must be aware that,
385 in the translated versions, the input data must appear in the same order:
386 "%s" for "John" before "%s" for "12:30", to comply with the order
387 imposed by the <literal>msprintf()</literal> input list of values.
388 This is not always possible, noticeably for languages far from
389 latin like right-to-left languages.
398 <title>Examples</title>
399 <programlisting role="example"><![CDATA[
402 // Messages ids are case-sensitive:
403 // "monday" is not an indexed native msgid, while "Monday" is:
404 gettext(["monday" ; "Monday"])
406 //_() is an alias of gettext():
409 // In Scilab, messages ids are in english:
411 _("Dimanche") // The french version can't be used as msgid
415 --> gettext(["monday" ; "Monday"])
424 --> setlanguage("ru");
434 Using a domain: Here, "tbx" is a predefined domain used to test translation features:
436 <programlisting role="example"><![CDATA[
438 msg = "%s: something not in Scilab.\n"; // unknown in the main native Scilab domain:
439 gettext(msg) // So, it is returned as is.
441 // If we use the domain without having declared it before,
442 // Scilab does not know where to find the translation:
443 gettext("tbx", msg) // The input message is still returned as is.
445 // So, let's declare the domain:
446 addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale");
447 gettext("tbx", msg) // Now it works
449 // The answer is a joke: Here it is still in english (while french is expected).
450 // The point is that it has been set as the french translation of the input msgid.
452 // The same msgid can be used as a native Scilab one with its native translations,
453 // and in one or several domains, with other translations:
454 msg = "%s: No more memory.\n";
455 [_(msg) ; _("tbx", msg)]
458 --> msg = "%s: something not in Scilab.\n"; // unknown in the main native Scilab domain:
461 %s: something not in Scilab.\n
463 --> // Scilab does not know yet where to find the translation:
464 --> gettext("tbx", msg)
466 %s: something not in Scilab.\n
468 --> // We declare the domain:
469 --> addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale");
470 --> gettext("tbx", msg) // Now it works
472 %s : it is true, that is not in Scilab.\n
474 --> msg = "%s: No more memory.\n";
475 --> [_(msg) ; _("tbx", msg)]
477 !%s : Plus de mémoire disponible.\n !
478 !%s : Overwrite Scilab translation.\n !
481 <refsection role="see also">
482 <title>See also</title>
483 <simplelist type="inline">
485 <link linkend="msprintf">msprintf</link>
488 <link linkend="setlanguage">setlanguage</link>
491 <link linkend="addlocalizationdomain">addlocalizationdomain</link>
494 <link linkend="tbx_generate_pofile">tbx_generate_pofile</link>
497 <link linkend="tbx_make">tbx_make . localization</link>
500 <link linkend="tbx_build_localization">tbx_build_localization</link>
503 <ulink url="https://www.gnu.org/software/gettext/">GNU gettext website</ulink>
508 <title>History</title>
511 <revnumber>5.5.0</revnumber>
512 <revdescription>Domain management added.</revdescription>