glib/ggettext.c

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright (C) 1995-1998  Peter Mattis, Spencer Kimball and Josh MacDonald
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  */
  19
  20 /*
  21  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
  22  * file for a list of people on the GLib Team.  See the ChangeLog
  23  * files for a list of changes.  These files are distributed with
  24  * GLib at ftp://ftp.gtk.org/pub/gtk/.
  25  */
  26
  27 #include "config.h"
  28
  29 #include "ggettext.h"
  30 #include "glibintl.h"
  31 #include "glib-private.h"
  32
  33 #include "galloca.h"
  34 #include "gthread.h"
  35 #include "gmem.h"
  36 #ifdef G_OS_WIN32
  37 #include "gwin32.h"
  38 #include "gfileutils.h"
  39 #include "gstrfuncs.h"
  40 #include "glib-init.h"
  41 #endif
  42
  43 #include <string.h>
  44 #include <locale.h>
  45 #include <libintl.h>
  46
  47 #ifdef G_OS_WIN32
  48
  49 /**
  50  * _glib_get_locale_dir:
  51  *
  52  * Return the path to the share\locale or lib\locale subfolder of the
  53  * GLib installation folder. The path is in the system codepage. We
  54  * have to use system codepage as bindtextdomain() doesn't have a
  55  * UTF-8 interface.
  56  */
  57 gchar *
  58 _glib_get_locale_dir (void)
  59 {
  60   gchar *install_dir = NULL, *locale_dir;
  61   gchar *retval = NULL;
  62
  63   if (glib_dll != NULL)
  64     install_dir = g_win32_get_package_installation_directory_of_module (glib_dll);
  65
  66   if (install_dir)
  67     {
  68       /*
  69        * Append "/share/locale" or "/lib/locale" depending on whether
  70        * autoconfigury detected GNU gettext or not.
  71        */
  72       const char *p = GLIB_LOCALE_DIR + strlen (GLIB_LOCALE_DIR);
  73       while (*--p != '/')
  74         ;
  75       while (*--p != '/')
  76         ;
  77
  78       locale_dir = g_build_filename (install_dir, p, NULL);
  79
  80       retval = g_win32_locale_filename_from_utf8 (locale_dir);
  81
  82       g_free (install_dir);
  83       g_free (locale_dir);
  84     }
  85
  86   if (retval)
  87     return retval;
  88   else
  89     return g_strdup ("");
  90 }
  91
  92 #undef GLIB_LOCALE_DIR
  93
  94 #endif /* G_OS_WIN32 */
  95
  96
  97 static void
  98 ensure_gettext_initialized (void)
  99 {
 100   static gsize initialised;
 101
 102   if (g_once_init_enter (&initialised))
 103     {
 104 #ifdef G_OS_WIN32
 105       gchar *tmp = _glib_get_locale_dir ();
 106       bindtextdomain (GETTEXT_PACKAGE, tmp);
 107       g_free (tmp);
 108 #else
 109       bindtextdomain (GETTEXT_PACKAGE, GLIB_LOCALE_DIR);
 110 #endif
 111 #    ifdef HAVE_BIND_TEXTDOMAIN_CODESET
 112       bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
 113 #    endif
 114       g_once_init_leave (&initialised, TRUE);
 115     }
 116 }
 117
 118 /**
 119  * glib_gettext:
 120  * @str: The string to be translated
 121  *
 122  * Returns the translated string from the glib translations.
 123  * This is an internal function and should only be used by
 124  * the internals of glib (such as libgio).
 125  *
 126  * Returns: the transation of @str to the current locale
 127  */
 128 const gchar *
 129 glib_gettext (const gchar *str)
 130 {
 131   ensure_gettext_initialized ();
 132
 133   return g_dgettext (GETTEXT_PACKAGE, str);
 134 }
 135
 136 /**
 137  * glib_pgettext:
 138  * @msgctxtid: a combined message context and message id, separated
 139  *   by a \004 character
 140  * @msgidoffset: the offset of the message id in @msgctxid
 141  *
 142  * This function is a variant of glib_gettext() which supports
 143  * a disambiguating message context. See g_dpgettext() for full
 144  * details.
 145  *
 146  * This is an internal function and should only be used by
 147  * the internals of glib (such as libgio).
 148  *
 149  * Returns: the translation of @str to the current locale
 150  */
 151 const gchar *
 152 glib_pgettext (const gchar *msgctxtid,
 153                gsize        msgidoffset)
 154 {
 155   ensure_gettext_initialized ();
 156
 157   return g_dpgettext (GETTEXT_PACKAGE, msgctxtid, msgidoffset);
 158 }
 159
 160 /**
 161  * g_strip_context:
 162  * @msgid: a string
 163  * @msgval: another string
 164  *
 165  * An auxiliary function for gettext() support (see Q_()).
 166  *
 167  * Return value: @msgval, unless @msgval is identical to @msgid
 168  *     and contains a '|' character, in which case a pointer to
 169  *     the substring of msgid after the first '|' character is returned.
 170  *
 171  * Since: 2.4
 172  */
 173 const gchar *
 174 g_strip_context (const gchar *msgid,
 175                  const gchar *msgval)
 176 {
 177   if (msgval == msgid)
 178     {
 179       const char *c = strchr (msgid, '|');
 180       if (c != NULL)
 181         return c + 1;
 182     }
 183
 184   return msgval;
 185 }
 186
 187 /**
 188  * g_dpgettext:
 189  * @domain: (allow-none): the translation domain to use, or %NULL to use
 190  *   the domain set with textdomain()
 191  * @msgctxtid: a combined message context and message id, separated
 192  *   by a \004 character
 193  * @msgidoffset: the offset of the message id in @msgctxid
 194  *
 195  * This function is a variant of g_dgettext() which supports
 196  * a disambiguating message context. GNU gettext uses the
 197  * '\004' character to separate the message context and
 198  * message id in @msgctxtid.
 199  * If 0 is passed as @msgidoffset, this function will fall back to
 200  * trying to use the deprecated convention of using "|" as a separation
 201  * character.
 202  *
 203  * This uses g_dgettext() internally. See that functions for differences
 204  * with dgettext() proper.
 205  *
 206  * Applications should normally not use this function directly,
 207  * but use the C_() macro for translations with context.
 208  *
 209  * Returns: The translated string
 210  *
 211  * Since: 2.16
 212  */
 213 const gchar *
 214 g_dpgettext (const gchar *domain,
 215              const gchar *msgctxtid,
 216              gsize        msgidoffset)
 217 {
 218   const gchar *translation;
 219   gchar *sep;
 220
 221   translation = g_dgettext (domain, msgctxtid);
 222
 223   if (translation == msgctxtid)
 224     {
 225       if (msgidoffset > 0)
 226         return msgctxtid + msgidoffset;
 227       sep = strchr (msgctxtid, '|');
 228
 229       if (sep)
 230         {
 231           /* try with '\004' instead of '|', in case
 232            * xgettext -kQ_:1g was used
 233            */
 234           gchar *tmp = g_alloca (strlen (msgctxtid) + 1);
 235           strcpy (tmp, msgctxtid);
 236           tmp[sep - msgctxtid] = '\004';
 237
 238           translation = g_dgettext (domain, tmp);
 239
 240           if (translation == tmp)
 241             return sep + 1;
 242         }
 243     }
 244
 245   return translation;
 246 }
 247
 248 /* This function is taken from gettext.h
 249  * GNU gettext uses '\004' to separate context and msgid in .mo files.
 250  */
 251 /**
 252  * g_dpgettext2:
 253  * @domain: (allow-none): the translation domain to use, or %NULL to use
 254  *   the domain set with textdomain()
 255  * @context: the message context
 256  * @msgid: the message
 257  *
 258  * This function is a variant of g_dgettext() which supports
 259  * a disambiguating message context. GNU gettext uses the
 260  * '\004' character to separate the message context and
 261  * message id in @msgctxtid.
 262  *
 263  * This uses g_dgettext() internally. See that functions for differences
 264  * with dgettext() proper.
 265  *
 266  * This function differs from C_() in that it is not a macro and
 267  * thus you may use non-string-literals as context and msgid arguments.
 268  *
 269  * Returns: The translated string
 270  *
 271  * Since: 2.18
 272  */
 273 const gchar *
 274 g_dpgettext2 (const gchar *domain,
 275               const gchar *msgctxt,
 276               const gchar *msgid)
 277 {
 278   size_t msgctxt_len = strlen (msgctxt) + 1;
 279   size_t msgid_len = strlen (msgid) + 1;
 280   const char *translation;
 281   char* msg_ctxt_id;
 282
 283   msg_ctxt_id = g_alloca (msgctxt_len + msgid_len);
 284
 285   memcpy (msg_ctxt_id, msgctxt, msgctxt_len - 1);
 286   msg_ctxt_id[msgctxt_len - 1] = '\004';
 287   memcpy (msg_ctxt_id + msgctxt_len, msgid, msgid_len);
 288
 289   translation = g_dgettext (domain, msg_ctxt_id);
 290
 291   if (translation == msg_ctxt_id)
 292     {
 293       /* try the old way of doing message contexts, too */
 294       msg_ctxt_id[msgctxt_len - 1] = '|';
 295       translation = g_dgettext (domain, msg_ctxt_id);
 296
 297       if (translation == msg_ctxt_id)
 298         return msgid;
 299     }
 300
 301   return translation;
 302 }
 303
 304 static gboolean
 305 _g_dgettext_should_translate (void)
 306 {
 307   static gsize translate = 0;
 308   enum {
 309     SHOULD_TRANSLATE = 1,
 310     SHOULD_NOT_TRANSLATE = 2
 311   };
 312
 313   if (G_UNLIKELY (g_once_init_enter (&translate)))
 314     {
 315       gboolean should_translate = TRUE;
 316
 317       const char *default_domain     = textdomain (NULL);
 318       const char *translator_comment = gettext ("");
 319 #ifndef G_OS_WIN32
 320       const char *translate_locale   = setlocale (LC_MESSAGES, NULL);
 321 #else
 322       const char *translate_locale   = g_win32_getlocale ();
 323 #endif
 324       /* We should NOT translate only if all the following hold:
 325        *   - user has called textdomain() and set textdomain to non-default
 326        *   - default domain has no translations
 327        *   - locale does not start with "en_" and is not "C"
 328        *
 329        * Rationale:
 330        *   - If text domain is still the default domain, maybe user calls
 331        *     it later. Continue with old behavior of translating.
 332        *   - If locale starts with "en_", we can continue using the
 333        *     translations even if the app doesn't have translations for
 334        *     this locale.  That is, en_UK and en_CA for example.
 335        *   - If locale is "C", maybe user calls setlocale(LC_ALL,"") later.
 336        *     Continue with old behavior of translating.
 337        */
 338       if (!default_domain || !translator_comment || !translate_locale ||
 339           (0 != strcmp (default_domain, "messages") &&
 340           '\0' == *translator_comment &&
 341           0 != strncmp (translate_locale, "en_", 3) &&
 342           0 != strcmp (translate_locale, "C")))
 343         should_translate = FALSE;
 344
 345       g_once_init_leave (&translate,
 346                          should_translate ?
 347                          SHOULD_TRANSLATE :
 348                          SHOULD_NOT_TRANSLATE);
 349     }
 350
 351   return translate == SHOULD_TRANSLATE;
 352 }
 353
 354 /**
 355  * g_dgettext:
 356  * @domain: (allow-none): the translation domain to use, or %NULL to use
 357  *   the domain set with textdomain()
 358  * @msgid: message to translate
 359  *
 360  * This function is a wrapper of dgettext() which does not translate
 361  * the message if the default domain as set with textdomain() has no
 362  * translations for the current locale.
 363  *
 364  * The advantage of using this function over dgettext() proper is that
 365  * libraries using this function (like GTK+) will not use translations
 366  * if the application using the library does not have translations for
 367  * the current locale.  This results in a consistent English-only
 368  * interface instead of one having partial translations.  For this
 369  * feature to work, the call to textdomain() and setlocale() should
 370  * precede any g_dgettext() invocations.  For GTK+, it means calling
 371  * textdomain() before gtk_init or its variants.
 372  *
 373  * This function disables translations if and only if upon its first
 374  * call all the following conditions hold:
 375  * <itemizedlist>
 376  * <listitem>@domain is not %NULL</listitem>
 377  * <listitem>textdomain() has been called to set a default text domain</listitem>
 378  * <listitem>there is no translations available for the default text domain
 379  *           and the current locale</listitem>
 380  * <listitem>current locale is not "C" or any English locales (those
 381  *           starting with "en_")</listitem>
 382  * </itemizedlist>
 383  *
 384  * Note that this behavior may not be desired for example if an application
 385  * has its untranslated messages in a language other than English.  In those
 386  * cases the application should call textdomain() after initializing GTK+.
 387  *
 388  * Applications should normally not use this function directly,
 389  * but use the _() macro for translations.
 390  *
 391  * Returns: The translated string
 392  *
 393  * Since: 2.18
 394  */
 395 const gchar *
 396 g_dgettext (const gchar *domain,
 397             const gchar *msgid)
 398 {
 399   if (domain && G_UNLIKELY (!_g_dgettext_should_translate ()))
 400     return msgid;
 401
 402   return dgettext (domain, msgid);
 403 }
 404
 405 /**
 406  * g_dcgettext:
 407  * @domain: (allow-none): the translation domain to use, or %NULL to use
 408  *   the domain set with textdomain()
 409  * @msgid: message to translate
 410  * @category: a locale category
 411  *
 412  * This is a variant of g_dgettext() that allows specifying a locale
 413  * category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for
 414  * more information about how this functions differs from calling
 415  * dcgettext() directly.
 416  *
 417  * Returns: the translated string for the given locale category
 418  *
 419  * Since: 2.26
 420  */
 421 const gchar *
 422 g_dcgettext (const gchar *domain,
 423              const gchar *msgid,
 424              gint         category)
 425 {
 426   if (domain && G_UNLIKELY (!_g_dgettext_should_translate ()))
 427     return msgid;
 428
 429   return dcgettext (domain, msgid, category);
 430 }
 431
 432 /**
 433  * g_dngettext:
 434  * @domain: (allow-none): the translation domain to use, or %NULL to use
 435  *   the domain set with textdomain()
 436  * @msgid: message to translate
 437  * @msgid_plural: plural form of the message
 438  * @n: the quantity for which translation is needed
 439  *
 440  * This function is a wrapper of dngettext() which does not translate
 441  * the message if the default domain as set with textdomain() has no
 442  * translations for the current locale.
 443  *
 444  * See g_dgettext() for details of how this differs from dngettext()
 445  * proper.
 446  *
 447  * Returns: The translated string
 448  *
 449  * Since: 2.18
 450  */
 451 const gchar *
 452 g_dngettext (const gchar *domain,
 453              const gchar *msgid,
 454              const gchar *msgid_plural,
 455              gulong       n)
 456 {
 457   if (domain && G_UNLIKELY (!_g_dgettext_should_translate ()))
 458     return n == 1 ? msgid : msgid_plural;
 459
 460   return dngettext (domain, msgid, msgid_plural, n);
 461 }
 462
 463
 464 /**
 465  * SECTION:i18n
 466  * @title: Internationalization
 467  * @short_description: gettext support macros
 468  * @see_also: the gettext manual
 469  *
 470  * GLib doesn't force any particular localization method upon its users.
 471  * But since GLib itself is localized using the gettext() mechanism, it seems
 472  * natural to offer the de-facto standard gettext() support macros in an
 473  * easy-to-use form.
 474  *
 475  * In order to use these macros in an application, you must include
 476  * <filename>glib/gi18n.h</filename>. For use in a library, you must include
 477  * <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
 478  * the GETTEXT_PACKAGE macro suitably for your library:
 479  * |[
 480  * &num;define GETTEXT_PACKAGE "gtk20"
 481  * &num;include &lt;glib/gi18n-lib.h&gt;
 482  * ]|
 483  * For an application, note that you also have to call bindtextdomain(),
 484  * bind_textdomain_codeset(), textdomain() and setlocale() early on in your
 485  * main() to make gettext() work.
 486  *
 487  * For a library, you only have to call bindtextdomain() and
 488  * bind_textdomain_codeset() in your initialization function. If your library
 489  * doesn't have an initialization function, you can call the functions before
 490  * the first translated message.
 491  *
 492  * The gettext manual covers details of how to set up message extraction
 493  * with xgettext.
 494  */
 495
 496 /**
 497  * _:
 498  * @String: the string to be translated
 499  *
 500  * Marks a string for translation, gets replaced with the translated string
 501  * at runtime.
 502  *
 503  * Since: 2.4
 504  */
 505
 506 /**
 507  * Q_:
 508  * @String: the string to be translated, with a '|'-separated prefix
 509  *     which must not be translated
 510  *
 511  * Like _(), but handles context in message ids. This has the advantage
 512  * that the string can be adorned with a prefix to guarantee uniqueness
 513  * and provide context to the translator.
 514  *
 515  * One use case given in the gettext manual is GUI translation, where one
 516  * could e.g. disambiguate two "Open" menu entries as "File|Open" and
 517  * "Printer|Open". Another use case is the string "Russian" which may
 518  * have to be translated differently depending on whether it's the name
 519  * of a character set or a language. This could be solved by using
 520  * "charset|Russian" and "language|Russian".
 521  *
 522  * See the C_() macro for a different way to mark up translatable strings
 523  * with context.
 524  *
 525  * <note><para>If you are using the Q_() macro, you need to make sure
 526  * that you pass <option>--keyword=Q_</option> to xgettext when extracting
 527  * messages. If you are using GNU gettext >= 0.15, you can also use
 528  * <option>--keyword=Q_:1g</option> to let xgettext split the context
 529  * string off into a msgctxt line in the po file.</para></note>
 530  *
 531  * Returns: the translated message
 532  *
 533  * Since: 2.4
 534  */
 535
 536 /**
 537  * C_:
 538  * @Context: a message context, must be a string literal
 539  * @String: a message id, must be a string literal
 540  *
 541  * Uses gettext to get the translation for @String. @Context is
 542  * used as a context. This is mainly useful for short strings which
 543  * may need different translations, depending on the context in which
 544  * they are used.
 545  * |[
 546  * label1 = C_("Navigation", "Back");
 547  * label2 = C_("Body part", "Back");
 548  * ]|
 549  *
 550  * <note><para>If you are using the C_() macro, you need to make sure
 551  * that you pass <option>--keyword=C_:1c,2</option> to xgettext when
 552  * extracting messages. Note that this only works with GNU
 553  * gettext >= 0.15.</para></note>
 554  *
 555  * Returns: the translated message
 556  *
 557  * Since: 2.16
 558  */
 559
 560 /**
 561  * N_:
 562  * @String: the string to be translated
 563  *
 564  * Only marks a string for translation. This is useful in situations
 565  * where the translated strings can't be directly used, e.g. in string
 566  * array initializers. To get the translated string, call gettext()
 567  * at runtime.
 568  * |[
 569  * {
 570  *   static const char *messages[] = {
 571  *     N_("some very meaningful message"),
 572  *     N_("and another one")
 573  *   };
 574  *   const char *string;
 575  *   ...
 576  *   string
 577  *     = index &gt; 1 ? _("a default message") : gettext (messages[index]);
 578  *
 579  *   fputs (string);
 580  *   ...
 581  * }
 582  * ]|
 583  *
 584  * Since: 2.4
 585  */
 586
 587 /**
 588  * NC_:
 589  * @Context: a message context, must be a string literal
 590  * @String: a message id, must be a string literal
 591  *
 592  * Only marks a string for translation, with context.
 593  * This is useful in situations where the translated strings can't
 594  * be directly used, e.g. in string array initializers. To get the
 595  * translated string, you should call g_dpgettext2() at runtime.
 596  *
 597  * |[
 598  * {
 599  *   static const char *messages[] = {
 600  *     NC_("some context", "some very meaningful message"),
 601  *     NC_("some context", "and another one")
 602  *   };
 603  *   const char *string;
 604  *   ...
 605  *   string
 606  *     = index &gt; 1 ? g_dpgettext2 (NULL, "some context", "a default message")
 607  *                    : g_dpgettext2 (NULL, "some context", messages[index]);
 608  *
 609  *   fputs (string);
 610  *   ...
 611  * }
 612  * ]|
 613  *
 614  * <note><para>If you are using the NC_() macro, you need to make sure
 615  * that you pass <option>--keyword=NC_:1c,2</option> to xgettext when
 616  * extracting messages. Note that this only works with GNU gettext >= 0.15.
 617  * Intltool has support for the NC_() macro since version 0.40.1.
 618  * </para></note>
 619  *
 620  * Since: 2.18
 621  */
 622