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.1 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, see <http://www.gnu.org/licenses/>.
16 */
17
18/*
19 * Modified by the GLib Team and others 1997-2000. See the AUTHORS
20 * file for a list of people on the GLib Team. See the ChangeLog
21 * files for a list of changes. These files are distributed with
22 * GLib at ftp://ftp.gtk.org/pub/gtk/.
23 */
24
25#include "config.h"
26
27#include "ggettext.h"
28#include "glibintl.h"
29#include "glib-private.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 */
55gchar *
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
95static void
96ensure_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, codeset: "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 translation of @str to the current locale
125 */
126const gchar *
127glib_gettext (const gchar *str)
128{
129 ensure_gettext_initialized ();
130
131 return g_dgettext (GETTEXT_PACKAGE, msgid: 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 translation of @str to the current locale
148 */
149const gchar *
150glib_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 * Returns: @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 */
171const gchar *
172g_strip_context (const gchar *msgid,
173 const gchar *msgval)
174{
175 if (msgval == msgid)
176 {
177 const char *c = strchr (s: msgid, c: '|');
178 if (c != NULL)
179 return c + 1;
180 }
181
182 return msgval;
183}
184
185/**
186 * g_dpgettext:
187 * @domain: (nullable): 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 */
211const gchar *
212g_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, msgid: msgctxtid);
220
221 if (translation == msgctxtid)
222 {
223 if (msgidoffset > 0)
224 return msgctxtid + msgidoffset;
225 sep = strchr (s: msgctxtid, c: '|');
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 (dest: tmp, src: msgctxtid);
234 tmp[sep - msgctxtid] = '\004';
235
236 translation = g_dgettext (domain, msgid: 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: (nullable): 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 */
271const gchar *
272g_dpgettext2 (const gchar *domain,
273 const gchar *msgctxt,
274 const gchar *msgid)
275{
276 size_t msgctxt_len = strlen (s: msgctxt) + 1;
277 size_t msgid_len = strlen (s: 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 (dest: msg_ctxt_id, src: msgctxt, n: msgctxt_len - 1);
284 msg_ctxt_id[msgctxt_len - 1] = '\004';
285 memcpy (dest: msg_ctxt_id + msgctxt_len, src: msgid, n: msgid_len);
286
287 translation = g_dgettext (domain, msgid: 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, msgid: msg_ctxt_id);
294
295 if (translation == msg_ctxt_id)
296 return msgid;
297 }
298
299 return translation;
300}
301
302static 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 (!default_domain || !translator_comment || !translate_locale ||
337 (0 != strcmp (s1: default_domain, s2: "messages") &&
338 '\0' == *translator_comment &&
339 0 != strncmp (s1: translate_locale, s2: "en_", n: 3) &&
340 0 != strcmp (s1: translate_locale, s2: "C")))
341 should_translate = FALSE;
342
343 g_once_init_leave (&translate,
344 should_translate ?
345 SHOULD_TRANSLATE :
346 SHOULD_NOT_TRANSLATE);
347 }
348
349 return translate == SHOULD_TRANSLATE;
350}
351
352/**
353 * g_dgettext:
354 * @domain: (nullable): the translation domain to use, or %NULL to use
355 * the domain set with textdomain()
356 * @msgid: message to translate
357 *
358 * This function is a wrapper of dgettext() which does not translate
359 * the message if the default domain as set with textdomain() has no
360 * translations for the current locale.
361 *
362 * The advantage of using this function over dgettext() proper is that
363 * libraries using this function (like GTK+) will not use translations
364 * if the application using the library does not have translations for
365 * the current locale. This results in a consistent English-only
366 * interface instead of one having partial translations. For this
367 * feature to work, the call to textdomain() and setlocale() should
368 * precede any g_dgettext() invocations. For GTK+, it means calling
369 * textdomain() before gtk_init or its variants.
370 *
371 * This function disables translations if and only if upon its first
372 * call all the following conditions hold:
373 *
374 * - @domain is not %NULL
375 *
376 * - textdomain() has been called to set a default text domain
377 *
378 * - there is no translations available for the default text domain
379 * and the current locale
380 *
381 * - current locale is not "C" or any English locales (those
382 * starting with "en_")
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 */
395const gchar *
396g_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: (nullable): 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 `LC_MESSAGES`. 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 */
421const gchar *
422g_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 (domainname: domain, msgid: msgid, category: category);
430}
431
432/**
433 * g_dngettext:
434 * @domain: (nullable): 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 */
451const gchar *
452g_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 * `<glib/gi18n.h>`. For use in a library, you must include
477 * `<glib/gi18n-lib.h>`
478 * after defining the %GETTEXT_PACKAGE macro suitably for your library:
479 * |[<!-- language="C" -->
480 * #define GETTEXT_PACKAGE "gtk20"
481 * #include <glib/gi18n-lib.h>
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. For example:
486 * |[<!-- language="C" -->
487 * #include <glib/gi18n.h>
488 * #include <locale.h>
489 *
490 * int
491 * main (int argc, char **argv)
492 * {
493 * setlocale (LC_ALL, "");
494 * bindtextdomain (GETTEXT_PACKAGE, DATADIR "/locale");
495 * bind_textdomain_codeset (GETTEXT_PACKAGE, "UTF-8");
496 * textdomain (GETTEXT_PACKAGE);
497 *
498 * // Rest of your application.
499 * }
500 * ]|
501 * where `DATADIR` is as typically provided by automake or Meson.
502 *
503 * For a library, you only have to call bindtextdomain() and
504 * bind_textdomain_codeset() in your initialization function. If your library
505 * doesn't have an initialization function, you can call the functions before
506 * the first translated message.
507 *
508 * The
509 * [gettext manual](http://www.gnu.org/software/gettext/manual/gettext.html#Maintainers)
510 * covers details of how to integrate gettext into a project’s build system and
511 * workflow.
512 */
513
514/**
515 * _:
516 * @String: the string to be translated
517 *
518 * Marks a string for translation, gets replaced with the translated string
519 * at runtime.
520 *
521 * Since: 2.4
522 */
523
524/**
525 * Q_:
526 * @String: the string to be translated, with a '|'-separated prefix
527 * which must not be translated
528 *
529 * Like _(), but handles context in message ids. This has the advantage
530 * that the string can be adorned with a prefix to guarantee uniqueness
531 * and provide context to the translator.
532 *
533 * One use case given in the gettext manual is GUI translation, where one
534 * could e.g. disambiguate two "Open" menu entries as "File|Open" and
535 * "Printer|Open". Another use case is the string "Russian" which may
536 * have to be translated differently depending on whether it's the name
537 * of a character set or a language. This could be solved by using
538 * "charset|Russian" and "language|Russian".
539 *
540 * See the C_() macro for a different way to mark up translatable strings
541 * with context.
542 *
543 * If you are using the Q_() macro, you need to make sure that you pass
544 * `--keyword=Q_` to xgettext when extracting messages.
545 * If you are using GNU gettext >= 0.15, you can also use
546 * `--keyword=Q_:1g` to let xgettext split the context
547 * string off into a msgctxt line in the po file.
548 *
549 * Returns: the translated message
550 *
551 * Since: 2.4
552 */
553
554/**
555 * C_:
556 * @Context: a message context, must be a string literal
557 * @String: a message id, must be a string literal
558 *
559 * Uses gettext to get the translation for @String. @Context is
560 * used as a context. This is mainly useful for short strings which
561 * may need different translations, depending on the context in which
562 * they are used.
563 * |[<!-- language="C" -->
564 * label1 = C_("Navigation", "Back");
565 * label2 = C_("Body part", "Back");
566 * ]|
567 *
568 * If you are using the C_() macro, you need to make sure that you pass
569 * `--keyword=C_:1c,2` to xgettext when extracting messages.
570 * Note that this only works with GNU gettext >= 0.15.
571 *
572 * Returns: the translated message
573 *
574 * Since: 2.16
575 */
576
577/**
578 * N_:
579 * @String: the string to be translated
580 *
581 * Only marks a string for translation. This is useful in situations
582 * where the translated strings can't be directly used, e.g. in string
583 * array initializers. To get the translated string, call gettext()
584 * at runtime.
585 * |[<!-- language="C" -->
586 * {
587 * static const char *messages[] = {
588 * N_("some very meaningful message"),
589 * N_("and another one")
590 * };
591 * const char *string;
592 * ...
593 * string
594 * = index &gt; 1 ? _("a default message") : gettext (messages[index]);
595 *
596 * fputs (string);
597 * ...
598 * }
599 * ]|
600 *
601 * Since: 2.4
602 */
603
604/**
605 * NC_:
606 * @Context: a message context, must be a string literal
607 * @String: a message id, must be a string literal
608 *
609 * Only marks a string for translation, with context.
610 * This is useful in situations where the translated strings can't
611 * be directly used, e.g. in string array initializers. To get the
612 * translated string, you should call g_dpgettext2() at runtime.
613 *
614 * |[<!-- language="C" -->
615 * {
616 * static const char *messages[] = {
617 * NC_("some context", "some very meaningful message"),
618 * NC_("some context", "and another one")
619 * };
620 * const char *string;
621 * ...
622 * string
623 * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
624 * : g_dpgettext2 (NULL, "some context", messages[index]);
625 *
626 * fputs (string);
627 * ...
628 * }
629 * ]|
630 *
631 * If you are using the NC_() macro, you need to make sure that you pass
632 * `--keyword=NC_:1c,2` to xgettext when extracting messages.
633 * Note that this only works with GNU gettext >= 0.15. Intltool has support
634 * for the NC_() macro since version 0.40.1.
635 *
636 * Since: 2.18
637 */
638

source code of gtk/subprojects/glib/glib/ggettext.c