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>