d56a2dada6b5403e5eb69c52c34967eb40c42898
[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) 2018 - Samuel GOUGEON
7  *
8  * Copyright (C) 2012 - 2016 - Scilab Enterprises
9  *
10  * This file is hereby licensed under the terms of the GNU GPL v2.0,
11  * pursuant to article 5.3.4 of the CeCILL v.2.1.
12  * This file was originally licensed under the terms of the CeCILL v2.1,
13  * and continues to be available under such terms.
14  * For more information, see the COPYING file which you should have received
15  * along with this program.
16  *
17  -->
18 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
19         xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
20         xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
21         xml:lang="en" xml:id="gettext">
22     <refnamediv>
23         <refname>gettext</refname>
24         <refpurpose>indexes or/and translates some indexed english messages</refpurpose>
25     </refnamediv>
26     <refnamediv xml:id="_">
27         <refname>_</refname>
28         <refpurpose>
29             Alias of gettext().
30         </refpurpose>
31     </refnamediv>
32     <refsynopsisdiv>
33         <title>Syntax</title>
34         <synopsis>
35             gettext("The literal reference message")
36             gettext(["item #1" ; "item#2"])
37             translated = gettext("The literal reference message")
38             translated = gettext(["item #1" ; "item#2"])
39             translated = gettext(msgid)
40             .. gettext(domain, ..)
41         </synopsis>
42     </refsynopsisdiv>
43     <refsection>
44         <title>Arguments</title>
45         <variablelist>
46             <varlistentry>
47                 <term>"The literal reference message"</term>
48                 <listitem>
49                     <para>
50                         Single literal text of an english message to be indexed or/and
51                         translated. A column of literal texts explicitly separated with
52                         semi-colons may also be specified.
53                     </para>
54                 </listitem>
55             </varlistentry>
56             <varlistentry>
57                 <term>msgid</term>
58                 <listitem>
59                     <para>
60                         single or array of messages identifiers (in english) to be translated,
61                         in a variable.
62                     </para>
63                 </listitem>
64             </varlistentry>
65             <varlistentry>
66                 <term>translated</term>
67                 <listitem>
68                     <para>
69                         Input messages translated in the current language of the Scilab session.
70                         If no translated version is available for an input message, the input
71                         version in english is returned. The input and output arrays have
72                         the same sizes.
73                     </para>
74                 </listitem>
75             </varlistentry>
76             <varlistentry>
77                 <term>domain</term>
78                 <listitem>
79                     <para>
80                         word of text: the name of a domain. When localizing an external module,
81                         <varname>domain</varname> may be usually set to the technical name of the
82                         module.
83                     </para>
84                     <para>
85                         <varname>domain</varname> can indifferently be a literal or a variable.
86                         It is case-sensitive.
87                     </para>
88                     <para>
89                         <varname>domain</varname> is required by
90                         <literal>tbx_generate_pofile()</literal> to make the literal msgid string
91                         indexed (harvesting stage. See below).
92                     </para>
93                     <para>
94                         When <literal>gettext(domain, msgid)</literal> is used to retrieve the
95                         translated version, <varname>domain</varname> is used to get the path
96                         to the directory where translations are stored, as beforehand registered
97                         with <literal>addlocalizationdomain(domain, path)</literal>.
98                     </para>
99                 </listitem>
100             </varlistentry>
101         </variablelist>
102     </refsection>
103     <refsection>
104         <title>Description</title>
105         <refsect3>
106         <title>Harvesting messages and overall processing</title>
107         <para>
108             <emphasis role="italic">gettext</emphasis> is a free and open external application
109             shipped within Scilab to support multilinguism for messages. This support consists in
110             4 main stages:
111             <orderedlist>
112                 <listitem>
113                     <para>
114                         <emphasis role="bold">Harvesting</emphasis> messages among the code and
115                         <emphasis role="bold">indexing</emphasis> them to be
116                         translated. For an external module, this is explicitly performed with the
117                         <literal>xgettext</literal> external binary, that is part of the
118                         <literal>gettext</literal> external application, and that is called by the
119                         <link linkend="tbx_generate_pofile">tbx_generate_pofile</link> Scilab function.
120                         In Scilab, it is also possible to use <literal>tbx_build_localization(..)</literal>
121                         or <literal>tbx_make . localization</literal>, that both call
122                         <literal>tbx_generate_pofile(..)</literal>.
123                     </para>
124                     <para>
125                         Each collected message is considered as an identifier (a message id, = msgid)
126                         for all its forthcoming translations. In Scilab, the reference language for
127                         identifiers is <emphasis role="italic">english</emphasis>.
128                         Therefore, the msgids to be indexed must be written in english.
129                     </para>
130                     <para>
131                         Only <emphasis role="bold">single literal and in one piece messages</emphasis>
132                         being as <literal>gettext</literal> input argument are collected. Hence,
133                         the following syntaxes and cases won't index the considered message, and no
134                         further translated versions will be available:
135                     </para>
136                     <para>
137                         <table>
138                             <tr>
139                                 <th>#</th><th>Syntax</th><th>Status</th>
140                                 <th align="left">Harvesting results</th>
141                             </tr>
142                             <tr valign="top">
143                                 <th>1</th>
144                                 <td style="white-space:nowrap">
145                                     <literal>gettext("To be translated")</literal>
146                                 </td>
147                                 <td>OK</td>
148                                 <td>standard syntax</td>
149                             </tr>
150                             <tr valign="top">
151                                 <th>2</th>
152                                 <td style="white-space:pre"><literal>
153 msg = "To be translated";
154 gettext(msg)</literal>
155                                 </td>
156                                 <td>NOK</td>
157                                 <td>
158                                     The text is in a variable. It is not a literal.
159                                     It won't be indexed.
160                                     Nevertheless, this syntax will work to <emphasis>retrieve</emphasis>
161                                     the translated version, <emphasis>provided that the message
162                                     has been collected elsewhere in a right way</emphasis>.
163                                 </td>
164                             </tr>
165                             <tr valign="top">
166                                 <th>3</th>
167                                 <td style="white-space:nowrap">
168                                     <literal>gettext("To be" + " translated")</literal>
169                                 </td>
170                                 <td>NOK</td>
171                                 <td>
172                                     "To be" and " translated" are indexed as 2 separate msgid.
173                                     Then, since the concatenated msgid "To be translated" does not exist,
174                                     retrieving its translation will fail.
175                                 </td>
176                             </tr>
177                             <tr valign="top">
178                                 <th>4</th>
179                                 <td style="white-space:pre"><literal>
180 gettext("To be" + ..
181                   " translated")</literal>
182                                 </td>
183                                 <td>NOK</td>
184                                 <td>Same as #3</td>
185                             </tr>
186                             <tr valign="top">
187                                 <th>5</th>
188                                 <td style="white-space:nowrap">
189                                     <literal>gettext(["item#1", "item#2"])</literal>
190                                 </td>
191                                 <td>NOK</td>
192                                 <td>Only "item#1" is collected. "item#2" is ignored.</td>
193                             </tr>
194                             <tr valign="top">
195                                 <th>6</th>
196                                 <td style="white-space:nowrap">
197                                     <literal>gettext(["item#1"  "item#2"])</literal>
198                                 </td>
199                                 <td>NOK</td>
200                                 <td>
201                                     "item#1item#2" is indexed. Then, since "item#1" and "item#2"
202                                     are unknown separate msgid, retrieving their respective
203                                     translation will fail.
204                                 </td>
205                             </tr>
206                             <tr valign="top">
207                                 <th>7</th>
208                                 <td style="white-space:pre"><literal>
209 gettext(["item#1"
210          "item#2"])</literal>
211                                 </td>
212                                 <td>NOK</td>
213                                 <td>Same as #6</td>
214                             </tr>
215                             <tr valign="top">
216                                 <th>8</th>
217                                 <td style="white-space:nowrap">
218                                     <literal>gettext(["item#1" ; "item#2"])</literal>
219                                 </td>
220                                 <td>OK</td>
221                                 <td>"item#1" and "item#2" are indexed as separate msgids.</td>
222                             </tr>
223                             <tr valign="top">
224                                 <th>9</th>
225                                 <td style="white-space:pre"><literal>
226 gettext(["item#1" ;
227          "item#2"])</literal>
228                                 </td>
229                                 <td>OK</td>
230                                 <td>
231                                     Same as #8. Please take care of the semi-colon. Without it,
232                                     the case #7 fails.
233                                 </td>
234                             </tr>
235                         </table>
236                     </para>
237                     <important>
238                         For an external module,
239                         <link linkend="tbx_generate_pofile">tbx_generate_pofile()</link>
240                         harvests only <literal>gettext</literal> occurrences that specify a
241                         <varname>domain</varname>. It ignores any call to <literal>gettext</literal>
242                         with only one input argument.
243                         <para>
244                             Harvesting does not need to beforehand declare the
245                             <varname>domain</varname> with
246                             <literal>addlocalizationdomain()</literal>
247                         </para>
248                     </important>
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                 </listitem>
257                 <listitem>
258                     <para>
259                         All translated versions are bundled in a way that <literal>gettext(..)</literal>
260                         becomes efficient to retrieve the version in the current session's language.
261                         This is done by running <literal>tbx_generate_pofile()</literal> another
262                         time.
263                     </para>
264                 </listitem>
265                 <listitem>
266                     <para>
267                         Finally, some calls like <literal>gettext(message)</literal> or
268                         <literal>gettext("The message content")</literal> are used to retrieve and
269                         return the translated version.
270                     </para>
271                     <para>
272                         When the message is not a native Scilab one (for instance it is specific
273                         to an external module), the <varname>domain</varname> where the message
274                         and its translations can be found must be specified, as in
275                         <literal>gettext(domain, message)</literal>
276                         or <literal>gettext(domain, "The message content")</literal>.
277                         In this case, <literal>addlocalizationdomain(domain, path)</literal> must
278                         be run before in order to make <varname>domain</varname> pointing to
279                         the storage directory.
280                     </para>
281                 </listitem>
282             </orderedlist>
283         </para>
284         <para>
285             Most often, a message is declared to be harvested and is used to retrieve its
286             translated version through the same <literal>gettext("The literal message")</literal>
287             call.
288             However, it is not mandatory. Hence, a piece of code like
289             <literal>if %F, gettext("The literal message"), end</literal> will never execute
290             the <literal>gettext</literal> call, but is nevertherless meaningfull: It is here only
291             to make the message visible to the <literal>xgettext</literal> scanner/harvester.
292             Then, somewhere else in the code, it will be possible to use
293             <literal>msg = "The literal message"; gettext(msg)</literal> to return the translated
294             version.
295         </para>
296         <para>
297             As well, using several times the same literal
298             <literal>gettext("The literal message")</literal> call won't be rare, for example to
299             retrieve the translation in several files. In this case, the <literal>xgettext</literal>
300             harvester will collect the message only once, and the same translation will be returned
301             for all calls.
302         </para>
303         <warning>
304             Limitations: There is no way to translate a message
305             <itemizedlist>
306                 <listitem>
307                     <para>
308                     in a language other than the current session's one. If this is really required,
309                     the session's language will have to be temporarily switched to the desired
310                     language, then <literal>gettext()</literal> called, and at last the initial
311                     session's language restored.
312                     </para>
313                 </listitem>
314                 <listitem>
315                     <para>
316                         from a translated version rather than from the message id in english.
317                     </para>
318                 </listitem>
319             </itemizedlist>
320         </warning>
321         </refsect3>
322         <!-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -->
323         <refsect3>
324             <title>Messages</title>
325             <para>
326                 To be correctly processed, english messages must comply with a few rules:
327                 <itemizedlist>
328                     <listitem>
329                         <para>
330                             Messages identifiers are case-sensitive.
331                         </para>
332                     </listitem>
333                     <listitem>
334                         <para>
335                             Literal harvestable messages may be indifferently delimited with single
336                             or double quotes.
337                         </para>
338                         <warning>
339                             When <literal>gettext()</literal> or <literal>_()</literal> is used in
340                             an XML file such as in the preferences files of an external module, the
341                             literal domain string and the literal message id must no longer be
342                             delimited. For instance, <literal>_(my_domain, My message)</literal>
343                             will be used instead of <literal>_("my_domain", "My message")</literal>.
344                         </warning>
345                     </listitem>
346                     <listitem>
347                         <para>
348                         Double quotes must be avoided in the body of messages. Please use single quotes.
349                         </para>
350                     </listitem>
351                     <listitem>
352                         <para>
353                         Inner escaped sequences like "\t" "\n" etc are not interpreted, neither by
354                         the <literal>xgettext</literal> scanner nor by the <literal>gettext</literal>
355                         function. They are collected and stored as is in the messages.
356                         </para>
357                     </listitem>
358                     <listitem>
359                         <para>
360                             Some template messages may often include some "%" C-like directives
361                             aiming to be replaced with some input custom data through
362                             <literal>msprintf()</literal> at run time.
363                             For instance,
364                             <literal>msprintf("Hi %s, could you come at %s today?", "John", "12:30")</literal>
365                             will return <literal>"Hi John, could you come at 12:30 today?"</literal>.
366                         </para>
367                         <warning>
368                         <para>
369                             Now, let's assume that you wish to make the template message translatable:
370                             <literal>msg = _("Hi %s, could you come at %s today?")</literal>
371                             and <literal>msprintf(msg, "John", "12:30")</literal>
372                             will be used. However, the author or/and translaters must be aware that,
373                             in the translated versions, the input data must appear in the same order:
374                             "%s" for "John" before "%s" for "12:30", to comply with the order
375                             imposed by the <literal>msprintf()</literal> input list of values.
376                             This is not always possible, noticeably for languages far from
377                             latin like right-to-left languages.
378                         </para>
379                         </warning>
380                     </listitem>
381                 </itemizedlist>
382             </para>
383         </refsect3>
384     </refsection>
385     <refsection>
386         <title>Examples</title>
387         <programlisting role="example"><![CDATA[
388 setlanguage("fr");
389
390 // Messages ids are case-sensitive:
391 // "monday" is not an indexed native msgid, while "Monday" is:
392 gettext(["monday" ; "Monday"])
393
394 //_() is an alias of gettext():
395 _("Sunday")
396
397 // In Scilab, messages ids are in english:
398 setlanguage("ru");
399 _("Dimanche")       // The french version can't be used as msgid
400 _("Sunday")
401  ]]></programlisting>
402     <screen><![CDATA[
403 --> gettext(["monday" ; "Monday"])
404  ans  =
405 !monday  !
406 !Lundi   !
407
408 --> _("Sunday")
409  ans  =
410  Dimanche
411
412 --> setlanguage("ru");
413 --> _("Dimanche")
414  ans  =
415  Dimanche
416
417 --> _("Sunday")
418  ans  =
419  Воскресенье
420 ]]></screen>
421     <para>
422         Using a domain: Here, "tbx" is a predefined domain used to test translation features:
423     </para>
424         <programlisting role="example"><![CDATA[
425 setlanguage("fr");
426 msg = "%s: something not in Scilab.\n";  // unknown in the main native Scilab domain:
427 gettext(msg)          // So, it is returned as is.
428
429 //  If we use the domain without having declared it before,
430 //  Scilab does not know where to find the translation:
431 gettext("tbx", msg)   // The input message is still returned as is.
432
433 // So, let's declare the domain:
434 addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale");
435 gettext("tbx", msg)   // Now it works
436
437 // The answer is a joke: Here it is still in english (while french is expected).
438 // The point is that it has been set as the french translation of the input msgid.
439
440 // The same msgid can be used as a native Scilab one with its native translations,
441 // and in one or several domains, with other translations:
442 msg = "%s: No more memory.\n";
443 [_(msg) ; _("tbx", msg)]
444  ]]></programlisting>
445     <screen><![CDATA[
446 --> msg = "%s: something not in Scilab.\n"; // unknown in the main native Scilab domain:
447 --> gettext(msg)
448  ans  =
449  %s: something not in Scilab.\n
450
451 --> //  Scilab does not know yet where to find the translation:
452 --> gettext("tbx", msg)
453  ans  =
454  %s: something not in Scilab.\n
455
456 --> // We declare the domain:
457 --> addlocalizationdomain("tbx", "SCI/modules/localization/tests/unit_tests/locale");
458 --> gettext("tbx", msg)   // Now it works
459  ans  =
460  %s : it is true, that is not in Scilab.\n
461
462 --> msg = "%s: No more memory.\n";
463 --> [_(msg) ; _("tbx", msg)]
464  ans  =
465 !%s : Plus de mémoire disponible.\n    !
466 !%s : Overwrite Scilab translation.\n  !
467 ]]></screen>
468     </refsection>
469     <refsection role="see also">
470         <title>See also</title>
471         <simplelist type="inline">
472             <member>
473                 <link linkend="msprintf">msprintf</link>
474             </member>
475             <member>
476                 <link linkend="setlanguage">setlanguage</link>
477             </member>
478             <member>
479                 <link linkend="addlocalizationdomain">addlocalizationdomain</link>
480             </member>
481             <member>
482                 <link linkend="tbx_generate_pofile">tbx_generate_pofile</link>
483             </member>
484             <member>
485                 <link linkend="tbx_make">tbx_make . localization</link>
486             </member>
487             <member>
488                 <link linkend="tbx_build_localization">tbx_build_localization</link>
489             </member>
490             <member>
491                 <ulink url="https://www.gnu.org/software/gettext/">GNU gettext website</ulink>
492             </member>
493         </simplelist>
494     </refsection>
495     <refsection>
496         <title>History</title>
497         <revhistory>
498             <revision>
499                 <revnumber>5.5.0</revnumber>
500                 <revdescription>Domain management added.</revdescription>
501             </revision>
502         </revhistory>
503     </refsection>
504 </refentry>