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