[doc] misc. fix & improvements
[scilab.git] / scilab / modules / localization / help / en_US / gettext.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
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
8  *
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.
15  *
16  -->
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">
21     <refnamediv>
22         <refname>gettext</refname>
23         <refpurpose>indexes or/and translates some indexed english messages</refpurpose>
24     </refnamediv>
25     <refnamediv xml:id="_">
26         <refname>_</refname>
27         <refpurpose>
28             Alias of gettext().
29         </refpurpose>
30     </refnamediv>
31     <refsynopsisdiv>
32         <title>Syntax</title>
33         <synopsis>
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, ..)
40         </synopsis>
41     </refsynopsisdiv>
42     <refsection>
43         <title>Arguments</title>
44         <variablelist>
45             <varlistentry>
46                 <term>"The literal reference message"</term>
47                 <listitem>
48                     <para>
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.
52                     </para>
53                 </listitem>
54             </varlistentry>
55             <varlistentry>
56                 <term>msgid</term>
57                 <listitem>
58                     <para>
59                         single or array of messages identifiers (in english) to be translated,
60                         in a variable.
61                     </para>
62                 </listitem>
63             </varlistentry>
64             <varlistentry>
65                 <term>translated</term>
66                 <listitem>
67                     <para>
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
71                         the same sizes.
72                     </para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>domain</term>
77                 <listitem>
78                     <para>
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
81                         module.
82                     </para>
83                     <para>
84                         <varname>domain</varname> can indifferently be a literal or a variable.
85                         It is case-sensitive.
86                     </para>
87                     <para>
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).
91                     </para>
92                     <para>
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>.
97                     </para>
98                 </listitem>
99             </varlistentry>
100         </variablelist>
101     </refsection>
102     <refsection>
103         <title>Description</title>
104         <refsect3>
105         <title>Harvesting messages and overall processing</title>
106         <para>
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
109             4 main stages:
110             <orderedlist>
111                 <listitem>
112                     <para>
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>.
122                     </para>
123                     <para>
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.
128                     </para>
129                     <para>
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:
134                     </para>
135                     <para>
136                         <table>
137                             <tr>
138                                 <th>#</th><th>Syntax</th><th>Status</th>
139                                 <th align="left">Harvesting results</th>
140                             </tr>
141                             <tr valign="top">
142                                 <th>1</th>
143                                 <td style="white-space:nowrap">
144                                     <literal>gettext("To be translated")</literal>
145                                 </td>
146                                 <td>OK</td>
147                                 <td>standard syntax</td>
148                             </tr>
149                             <tr valign="top">
150                                 <th>2</th>
151                                 <td style="white-space:pre"><screen><![CDATA[
152 msg = "To be translated";
153 gettext(msg)]]></screen>
154                                 </td>
155                                 <td>NOK</td>
156                                 <td>
157                                     The text is in a variable. It is not a literal.
158                                     It won't be indexed.
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>.
162                                 </td>
163                             </tr>
164                             <tr valign="top">
165                                 <th>3</th>
166                                 <td style="white-space:nowrap">
167                                     <literal>gettext("To be" + " translated")</literal>
168                                 </td>
169                                 <td>NOK</td>
170                                 <td>
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.
174                                 </td>
175                             </tr>
176                             <tr valign="top">
177                                 <th>4</th>
178                                 <td style="white-space:pre"><screen><![CDATA[
179 gettext("To be" + ..
180         " translated")]]></screen>
181                                 </td>
182                                 <td>NOK</td>
183                                 <td>Same as #3</td>
184                             </tr>
185                             <tr valign="top">
186                                 <th>5</th>
187                                 <td style="white-space:nowrap">
188                                     <literal>gettext(["item#1", "item#2"])</literal>
189                                 </td>
190                                 <td>NOK</td>
191                                 <td>Only "item#1" is collected. "item#2" is ignored.</td>
192                             </tr>
193                             <tr valign="top">
194                                 <th>6</th>
195                                 <td style="white-space:nowrap">
196                                     <literal>gettext(["item#1"  "item#2"])</literal>
197                                 </td>
198                                 <td>NOK</td>
199                                 <td>
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.
203                                 </td>
204                             </tr>
205                             <tr valign="top">
206                                 <th>7</th>
207                                 <td style="white-space:pre"><screen><![CDATA[
208 gettext(["item#1"
209          "item#2"])]]></screen>
210                                 </td>
211                                 <td>NOK</td>
212                                 <td>Same as #6</td>
213                             </tr>
214                             <tr valign="top">
215                                 <th>8</th>
216                                 <td style="white-space:nowrap">
217                                     <literal>gettext(["item#1" ; "item#2"])</literal>
218                                 </td>
219                                 <td>OK</td>
220                                 <td>"item#1" and "item#2" are indexed as separate msgids.</td>
221                             </tr>
222                             <tr valign="top">
223                                 <th>9</th>
224                                 <td style="white-space:pre"><screen><![CDATA[
225 gettext(["item#1" ;
226          "item#2"])]]></screen>
227                                 </td>
228                                 <td>OK</td>
229                                 <td>
230                                     Same as #8. Please take care of the semi-colon. Without it,
231                                     the case #7 fails.
232                                 </td>
233                             </tr>
234                         </table>
235                     </para>
236                     <important>
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.
242                         <para>
243                             Harvesting does not need to beforehand declare the
244                             <varname>domain</varname> with
245                             <literal>addlocalizationdomain()</literal>
246                         </para>
247                     </important>
248                     <para/>
249                 </listitem>
250                 <listitem>
251                     <para>
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
254                         online.
255                     </para>
256                     <para/>
257                 </listitem>
258                 <listitem>
259                     <para>
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
263                         time.
264                     </para>
265                     <para/>
266                 </listitem>
267                 <listitem>
268                     <para>
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.
272                     </para>
273                     <para>
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.
282                     </para>
283                 </listitem>
284             </orderedlist>
285         </para>
286         <para>
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>
289             call.
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
296             version.
297         </para>
298         <para>
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
303             for all calls.
304         </para>
305         <warning>
306             Limitations: There is no way to translate a message
307             <itemizedlist>
308                 <listitem>
309                     <para>
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.
314                     </para>
315                 </listitem>
316                 <listitem>
317                     <para>
318                         from a translated version rather than from the message id in english.
319                     </para>
320                 </listitem>
321             </itemizedlist>
322         </warning>
323         </refsect3>
324         <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
325         <refsect3>
326             <title>Messages</title>
327             <para>
328                 To be correctly processed, english messages must comply with a few rules:
329                 <itemizedlist>
330                     <listitem>
331                         <para>
332                             Messages identifiers are case-sensitive.
333                         </para>
334                     </listitem>
335                     <listitem>
336                         <para>
337                             Literal harvestable messages may be indifferently delimited with single
338                             or double quotes.
339                         </para>
340                         <warning>
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
344                             delimited.
345                             <para/>
346                             For instance, <literal>_(my_domain, My message)</literal>
347                             will be used instead of <literal>_("my_domain", "My message")</literal>.
348                             <para>
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>.
355                             </para>
356                         </warning>
357                     </listitem>
358                     <listitem>
359                         <para>
360                         Double quotes must be avoided in the body of messages. Please use single quotes.
361                         </para>
362                     </listitem>
363                     <listitem>
364                         <para>
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.
368                         </para>
369                     </listitem>
370                     <listitem>
371                         <para>
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.
375                             For instance,
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>.
378                         </para>
379                         <warning>
380                         <para>
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.
390                         </para>
391                         </warning>
392                     </listitem>
393                 </itemizedlist>
394             </para>
395         </refsect3>
396     </refsection>
397     <refsection>
398         <title>Examples</title>
399         <programlisting role="example"><![CDATA[
400 setlanguage("fr");
401
402 // Messages ids are case-sensitive:
403 // "monday" is not an indexed native msgid, while "Monday" is:
404 gettext(["monday" ; "Monday"])
405
406 //_() is an alias of gettext():
407 _("Sunday")
408
409 // In Scilab, messages ids are in english:
410 setlanguage("ru");
411 _("Dimanche")       // The french version can't be used as msgid
412 _("Sunday")
413  ]]></programlisting>
414     <screen><![CDATA[
415 --> gettext(["monday" ; "Monday"])
416  ans  =
417 !monday  !
418 !Lundi   !
419
420 --> _("Sunday")
421  ans  =
422  Dimanche
423
424 --> setlanguage("ru");
425 --> _("Dimanche")
426  ans  =
427  Dimanche
428
429 --> _("Sunday")
430  ans  =
431  Воскресенье
432 ]]></screen>
433     <para>
434         Using a domain: Here, "tbx" is a predefined domain used to test translation features:
435     </para>
436         <programlisting role="example"><![CDATA[
437 setlanguage("fr");
438 msg = "%s: something not in Scilab.\n";  // unknown in the main native Scilab domain:
439 gettext(msg)          // So, it is returned as is.
440
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.
444
445 // So, let's declare the domain:
446 addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale");
447 gettext("tbx", msg)   // Now it works
448
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.
451
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)]
456  ]]></programlisting>
457     <screen><![CDATA[
458 --> msg = "%s: something not in Scilab.\n"; // unknown in the main native Scilab domain:
459 --> gettext(msg)
460  ans  =
461  %s: something not in Scilab.\n
462
463 --> //  Scilab does not know yet where to find the translation:
464 --> gettext("tbx", msg)
465  ans  =
466  %s: something not in Scilab.\n
467
468 --> // We declare the domain:
469 --> addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale");
470 --> gettext("tbx", msg)   // Now it works
471  ans  =
472  %s : it is true, that is not in Scilab.\n
473
474 --> msg = "%s: No more memory.\n";
475 --> [_(msg) ; _("tbx", msg)]
476  ans  =
477 !%s : Plus de mémoire disponible.\n    !
478 !%s : Overwrite Scilab translation.\n  !
479 ]]></screen>
480     </refsection>
481     <refsection role="see also">
482         <title>See also</title>
483         <simplelist type="inline">
484             <member>
485                 <link linkend="msprintf">msprintf</link>
486             </member>
487             <member>
488                 <link linkend="setlanguage">setlanguage</link>
489             </member>
490             <member>
491                 <link linkend="addlocalizationdomain">addlocalizationdomain</link>
492             </member>
493             <member>
494                 <link linkend="tbx_generate_pofile">tbx_generate_pofile</link>
495             </member>
496             <member>
497                 <link linkend="tbx_make">tbx_make . localization</link>
498             </member>
499             <member>
500                 <link linkend="tbx_build_localization">tbx_build_localization</link>
501             </member>
502             <member>
503                 <ulink url="https://www.gnu.org/software/gettext/">GNU gettext website</ulink>
504             </member>
505         </simplelist>
506     </refsection>
507     <refsection>
508         <title>History</title>
509         <revhistory>
510             <revision>
511                 <revnumber>5.5.0</revnumber>
512                 <revdescription>Domain management added.</revdescription>
513             </revision>
514         </revhistory>
515     </refsection>
516 </refentry>