Cleanup: strcmp/strncmp -> STREQ/STREQLEN (in boolean usage).
[blender.git] / source / blender / python / intern / bpy_app_translations.c
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program 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
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * Contributor(s): Bastien Montagne
19  *
20  * ***** END GPL LICENSE BLOCK *****
21  */
22
23 /** \file blender/python/intern/bpy_app_translations.c
24  *  \ingroup pythonintern
25  *
26  * This file defines a singleton py object accessed via 'bpy.app.translations',
27  * which exposes various data and functions useful in i18n work.
28  * Most notably, it allows to extend main translations with py dicts.
29  */
30
31 #include <Python.h>
32 /* XXX Why bloody hell isn't that included in Python.h???? */
33 #include <structmember.h>
34
35 #include "BLI_utildefines.h"
36 #include "BLI_string.h"
37 #include "BLI_ghash.h"
38
39 #include "BPY_extern.h"
40 #include "bpy_app_translations.h"
41
42 #include "MEM_guardedalloc.h"
43
44 #include "BLF_translation.h"
45
46 #include "RNA_types.h"
47
48 #include "../generic/python_utildefines.h"
49
50 typedef struct
51 {
52         PyObject_HEAD
53         /* The string used to separate context from actual message in PY_TRANSLATE RNA props. */
54         const char *context_separator;
55         /* A "named tuple" (StructSequence actually...) containing all C-defined contexts. */
56         PyObject *contexts;
57         /* A readonly mapping {C context id: python id}  (actually, a MappingProxy). */
58         PyObject *contexts_C_to_py;
59         /* A py dict containing all registered py dicts (order is more or less random, first match wins!). */
60         PyObject *py_messages;
61 } BlenderAppTranslations;
62
63 /* Our singleton instance pointer */
64 static BlenderAppTranslations *_translations = NULL;
65
66 #ifdef WITH_INTERNATIONAL
67
68 /***** Helpers for ghash *****/
69 typedef struct GHashKey {
70         const char *msgctxt;
71         const char *msgid;
72 } GHashKey;
73
74 static GHashKey *_ghashutil_keyalloc(const void *msgctxt, const void *msgid)
75 {
76         GHashKey *key = MEM_mallocN(sizeof(GHashKey), "Py i18n GHashKey");
77         key->msgctxt = BLI_strdup(BLF_is_default_context(msgctxt) ? BLF_I18NCONTEXT_DEFAULT_BPYRNA : msgctxt);
78         key->msgid = BLI_strdup(msgid);
79         return key;
80 }
81
82 static unsigned int _ghashutil_keyhash(const void *ptr)
83 {
84         const GHashKey *key = ptr;
85         unsigned int hash =  BLI_ghashutil_strhash(key->msgctxt);
86         return hash ^ BLI_ghashutil_strhash(key->msgid);
87 }
88
89 static bool _ghashutil_keycmp(const void *a, const void *b)
90 {
91         const GHashKey *A = a;
92         const GHashKey *B = b;
93
94         /* Note: comparing msgid first, most of the time it will be enough! */
95         if (BLI_ghashutil_strcmp(A->msgid, B->msgid) == false)
96                 return BLI_ghashutil_strcmp(A->msgctxt, B->msgctxt);
97         return true;  /* true means they are not equal! */
98 }
99
100 static void _ghashutil_keyfree(void *ptr)
101 {
102         const GHashKey *key = ptr;
103
104         /* We assume both msgctxt and msgid were BLI_strdup'ed! */
105         MEM_freeN((void *)key->msgctxt);
106         MEM_freeN((void *)key->msgid);
107         MEM_freeN((void *)key);
108 }
109
110 #define _ghashutil_valfree MEM_freeN
111
112 /***** Python's messages cache *****/
113
114 /* We cache all messages available for a given locale from all py dicts into a single ghash.
115  * Changing of locale is not so common, while looking for a message translation is, so let's try to optimize
116  * the later as much as we can!
117  * Note changing of locale, as well as (un)registering a message dict, invalidate that cache.
118  */
119 static GHash *_translations_cache = NULL;
120
121 static void _clear_translations_cache(void)
122 {
123         if (_translations_cache) {
124                 BLI_ghash_free(_translations_cache, _ghashutil_keyfree, _ghashutil_valfree);
125         }
126         _translations_cache = NULL;
127 }
128
129 static void _build_translations_cache(PyObject *py_messages, const char *locale)
130 {
131         PyObject *uuid, *uuid_dict;
132         Py_ssize_t pos = 0;
133         char *language = NULL, *language_country = NULL, *language_variant = NULL;
134
135         /* For each py dict, we'll search for full locale, then language+country, then language+variant,
136          * then only language keys... */
137         BLF_locale_explode(locale, &language, NULL, NULL, &language_country, &language_variant);
138
139         /* Clear the cached ghash if needed, and create a new one. */
140         _clear_translations_cache();
141         _translations_cache = BLI_ghash_new(_ghashutil_keyhash, _ghashutil_keycmp, __func__);
142
143         /* Iterate over all py dicts. */
144         while (PyDict_Next(py_messages, &pos, &uuid, &uuid_dict)) {
145                 PyObject *lang_dict;
146
147 #if 0
148                 PyObject_Print(uuid_dict, stdout, 0);
149                 printf("\n");
150 #endif
151
152                 /* Try to get first complete locale, then language+country, then language+variant, then only language */
153                 lang_dict = PyDict_GetItemString(uuid_dict, locale);
154                 if (!lang_dict && language_country) {
155                         lang_dict = PyDict_GetItemString(uuid_dict, language_country);
156                         locale = language_country;
157                 }
158                 if (!lang_dict && language_variant) {
159                         lang_dict = PyDict_GetItemString(uuid_dict, language_variant);
160                         locale = language_variant;
161                 }
162                 if (!lang_dict && language) {
163                         lang_dict = PyDict_GetItemString(uuid_dict, language);
164                         locale = language;
165                 }
166
167                 if (lang_dict) {
168                         PyObject *pykey, *trans;
169                         Py_ssize_t ppos = 0;
170
171                         if (!PyDict_Check(lang_dict)) {
172                                 printf("WARNING! In translations' dict of \"");
173                                 PyObject_Print(uuid, stdout, Py_PRINT_RAW);
174                                 printf("\":\n");
175                                 printf("    Each language key must have a dictionary as value, \"%s\" is not valid, skipping: ",
176                                        locale);
177                                 PyObject_Print(lang_dict, stdout, Py_PRINT_RAW);
178                                 printf("\n");
179                                 continue;
180                         }
181
182                         /* Iterate over all translations of the found language dict, and populate our ghash cache. */
183                         while (PyDict_Next(lang_dict, &ppos, &pykey, &trans)) {
184                                 GHashKey *key;
185                                 const char *msgctxt = NULL, *msgid = NULL;
186                                 bool invalid_key = false;
187
188                                 if ((PyTuple_CheckExact(pykey) == false) || (PyTuple_GET_SIZE(pykey) != 2)) {
189                                         invalid_key = true;
190                                 }
191                                 else {
192                                         PyObject *tmp = PyTuple_GET_ITEM(pykey, 0);
193                                         if (tmp == Py_None) {
194                                                 msgctxt = BLF_I18NCONTEXT_DEFAULT_BPYRNA;
195                                         }
196                                         else if (PyUnicode_Check(tmp)) {
197                                                 msgctxt = _PyUnicode_AsString(tmp);
198                                         }
199                                         else {
200                                                 invalid_key = true;
201                                         }
202
203                                         tmp = PyTuple_GET_ITEM(pykey, 1);
204                                         if (PyUnicode_Check(tmp)) {
205                                                 msgid = _PyUnicode_AsString(tmp);
206                                         }
207                                         else {
208                                                 invalid_key = true;
209                                         }
210                                 }
211
212                                 if (invalid_key) {
213                                         printf("WARNING! In translations' dict of \"");
214                                         PyObject_Print(uuid, stdout, Py_PRINT_RAW);
215                                         printf("\", %s language:\n", locale);
216                                         printf("    Keys must be tuples of (msgctxt [string or None], msgid [string]), "
217                                                "this one is not valid, skipping: ");
218                                         PyObject_Print(pykey, stdout, Py_PRINT_RAW);
219                                         printf("\n");
220                                         continue;
221                                 }
222                                 if (PyUnicode_Check(trans) == false) {
223                                         printf("WARNING! In translations' dict of \"");
224                                         PyObject_Print(uuid, stdout, Py_PRINT_RAW);
225                                         printf("\":\n");
226                                         printf("    Values must be strings, this one is not valid, skipping: ");
227                                         PyObject_Print(trans, stdout, Py_PRINT_RAW);
228                                         printf("\n");
229                                         continue;
230                                 }
231
232                                 key = _ghashutil_keyalloc(msgctxt, msgid);
233
234                                 /* Do not overwrite existing keys! */
235                                 if (BLI_ghash_lookup(_translations_cache, (void *)key)) {
236                                         continue;
237                                 }
238
239                                 BLI_ghash_insert(_translations_cache, key, BLI_strdup(_PyUnicode_AsString(trans)));
240                         }
241                 }
242         }
243
244         /* Clean up! */
245         MEM_SAFE_FREE(language);
246         MEM_SAFE_FREE(language_country);
247         MEM_SAFE_FREE(language_variant);
248 }
249
250 const char *BPY_app_translations_py_pgettext(const char *msgctxt, const char *msgid)
251 {
252 #define STATIC_LOCALE_SIZE 32  /* Should be more than enough! */
253
254         GHashKey *key;
255         static char locale[STATIC_LOCALE_SIZE] = "";
256         const char *tmp;
257
258         /* Just in case, should never happen! */
259         if (!_translations)
260                 return msgid;
261
262         tmp = BLF_lang_get();
263         if (!STREQ(tmp, locale) || !_translations_cache) {
264                 PyGILState_STATE _py_state;
265
266                 BLI_strncpy(locale, tmp, STATIC_LOCALE_SIZE);
267
268                 /* Locale changed or cache does not exist, refresh the whole cache! */
269                 /* This func may be called from C (i.e. outside of python interpreter 'context'). */
270                 _py_state = PyGILState_Ensure();
271
272                 _build_translations_cache(_translations->py_messages, locale);
273
274                 PyGILState_Release(_py_state);
275         }
276
277         /* And now, simply create the key (context, messageid) and find it in the cached dict! */
278         key = _ghashutil_keyalloc(msgctxt, msgid);
279
280         tmp = BLI_ghash_lookup(_translations_cache, key);
281
282         _ghashutil_keyfree((void *)key);
283
284         return tmp ? tmp : msgid;
285
286 #undef STATIC_LOCALE_SIZE
287 }
288
289 #endif  /* WITH_INTERNATIONAL */
290
291 PyDoc_STRVAR(app_translations_py_messages_register_doc,
292 ".. method:: register(module_name, translations_dict)\n"
293 "\n"
294 "   Registers an addon's UI translations.\n"
295 "\n"
296 "   .. note::\n"
297 "       Does nothing when Blender is built without internationalization support.\n"
298 "\n"
299 "   :arg module_name: The name identifying the addon.\n"
300 "   :type module_name: string\n"
301 "   :arg translations_dict: A dictionary built like that:\n"
302 "       ``{locale: {msg_key: msg_translation, ...}, ...}``\n"
303 "   :type translations_dict: dict\n"
304 "\n"
305 );
306 static PyObject *app_translations_py_messages_register(BlenderAppTranslations *self, PyObject *args, PyObject *kw)
307 {
308 #ifdef WITH_INTERNATIONAL
309         static const char *kwlist[] = {"module_name", "translations_dict", NULL};
310         PyObject *module_name, *uuid_dict;
311
312         if (!PyArg_ParseTupleAndKeywords(args, kw, "O!O!:bpy.app.translations.register", (char **)kwlist, &PyUnicode_Type,
313                                          &module_name, &PyDict_Type, &uuid_dict))
314         {
315                 return NULL;
316         }
317
318         if (PyDict_Contains(self->py_messages, module_name)) {
319                 PyErr_Format(PyExc_ValueError,
320                              "bpy.app.translations.register: translations message cache already contains some data for "
321                              "addon '%s'", (const char *)_PyUnicode_AsString(module_name));
322                 return NULL;
323         }
324
325         PyDict_SetItem(self->py_messages, module_name, uuid_dict);
326
327         /* Clear cached messages dict! */
328         _clear_translations_cache();
329 #else
330         (void)self;
331         (void)args;
332         (void)kw;
333 #endif
334
335         /* And we are done! */
336         Py_RETURN_NONE;
337 }
338
339 PyDoc_STRVAR(app_translations_py_messages_unregister_doc,
340 ".. method:: unregister(module_name)\n"
341 "\n"
342 "   Unregisters an addon's UI translations.\n"
343 "\n"
344 "   .. note::\n"
345 "       Does nothing when Blender is built without internationalization support.\n"
346 "\n"
347 "   :arg module_name: The name identifying the addon.\n"
348 "   :type module_name: string\n"
349 "\n"
350 );
351 static PyObject *app_translations_py_messages_unregister(BlenderAppTranslations *self, PyObject *args, PyObject *kw)
352 {
353 #ifdef WITH_INTERNATIONAL
354         static const char *kwlist[] = {"module_name", NULL};
355         PyObject *module_name;
356
357         if (!PyArg_ParseTupleAndKeywords(args, kw, "O!:bpy.app.translations.unregister", (char **)kwlist, &PyUnicode_Type,
358                                          &module_name))
359         {
360                 return NULL;
361         }
362
363         if (PyDict_Contains(self->py_messages, module_name)) {
364                 PyDict_DelItem(self->py_messages, module_name);
365                 /* Clear cached messages ghash! */
366                 _clear_translations_cache();
367         }
368 #else
369         (void)self;
370         (void)args;
371         (void)kw;
372 #endif
373
374         /* And we are done! */
375         Py_RETURN_NONE;
376 }
377
378 /***** C-defined contexts *****/
379 /* This is always available (even when WITH_INTERNATIONAL is not defined). */
380
381 static PyTypeObject BlenderAppTranslationsContextsType;
382
383 static BLF_i18n_contexts_descriptor _contexts[] = BLF_I18NCONTEXTS_DESC;
384
385 /* These fields are just empty placeholders, actual values get set in app_translations_struct().
386  * This allows us to avoid many handwriting, and above all, to keep all context definition stuff in BLF_translation.h!
387  */
388 static PyStructSequence_Field
389 app_translations_contexts_fields[ARRAY_SIZE(_contexts)] = {{NULL}};
390
391 static PyStructSequence_Desc app_translations_contexts_desc = {
392         (char *)"bpy.app.translations.contexts",     /* name */
393         (char *)"This named tuple contains all pre-defined translation contexts",    /* doc */
394         app_translations_contexts_fields,    /* fields */
395         ARRAY_SIZE(app_translations_contexts_fields) - 1
396 };
397
398 static PyObject *app_translations_contexts_make(void)
399 {
400         PyObject *translations_contexts;
401         BLF_i18n_contexts_descriptor *ctxt;
402         int pos = 0;
403
404         translations_contexts = PyStructSequence_New(&BlenderAppTranslationsContextsType);
405         if (translations_contexts == NULL) {
406                 return NULL;
407         }
408
409 #define SetObjString(item) PyStructSequence_SET_ITEM(translations_contexts, pos++, PyUnicode_FromString((item)))
410 #define SetObjNone() PyStructSequence_SET_ITEM(translations_contexts, pos++, Py_INCREF_RET(Py_None))
411
412         for (ctxt = _contexts; ctxt->c_id; ctxt++) {
413                 if (ctxt->value) {
414                         SetObjString(ctxt->value);
415                 }
416                 else {
417                         SetObjNone();
418                 }
419         }
420
421 #undef SetObjString
422 #undef SetObjNone
423
424         return translations_contexts;
425 }
426
427 /***** Main BlenderAppTranslations Py object definition *****/
428
429 PyDoc_STRVAR(app_translations_contexts_doc,
430         "A named tuple containing all pre-defined translation contexts.\n"
431         "\n"
432         ".. warning::\n"
433         "    Never use a (new) context starting with \"" BLF_I18NCONTEXT_DEFAULT_BPYRNA "\", it would be internally \n"
434         "    assimilated as the default one!\n"
435 );
436
437 PyDoc_STRVAR(app_translations_contexts_C_to_py_doc,
438         "A readonly dict mapping contexts' C-identifiers to their py-identifiers."
439 );
440
441 static PyMemberDef app_translations_members[] = {
442         {(char *)"contexts", T_OBJECT_EX, offsetof(BlenderAppTranslations, contexts), READONLY,
443                              app_translations_contexts_doc},
444         {(char *)"contexts_C_to_py", T_OBJECT_EX, offsetof(BlenderAppTranslations, contexts_C_to_py), READONLY,
445                                      app_translations_contexts_C_to_py_doc},
446         {NULL}
447 };
448
449 PyDoc_STRVAR(app_translations_locale_doc,
450         "The actual locale currently in use (will always return a void string when Blender is built without "
451         "internationalization support)."
452 );
453 static PyObject *app_translations_locale_get(PyObject *UNUSED(self), void *UNUSED(userdata))
454 {
455         return PyUnicode_FromString(BLF_lang_get());
456 }
457
458 /* Note: defining as getter, as (even if quite unlikely), this *may* change during runtime... */
459 PyDoc_STRVAR(app_translations_locales_doc, "All locales currently known by Blender (i.e. available as translations).");
460 static PyObject *app_translations_locales_get(PyObject *UNUSED(self), void *UNUSED(userdata))
461 {
462         PyObject *ret;
463         EnumPropertyItem *it, *items = BLF_RNA_lang_enum_properties();
464         int num_locales = 0, pos = 0;
465
466         if (items) {
467                 /* This is not elegant, but simple! */
468                 for (it = items; it->identifier; it++) {
469                         if (it->value)
470                                 num_locales++;
471                 }
472         }
473
474         ret = PyTuple_New(num_locales);
475
476         if (items) {
477                 for (it = items; it->identifier; it++) {
478                         if (it->value)
479                                 PyTuple_SET_ITEM(ret, pos++, PyUnicode_FromString(it->description));
480                 }
481         }
482
483         return ret;
484 }
485
486 static PyGetSetDef app_translations_getseters[] = {
487         /* {name, getter, setter, doc, userdata} */
488         {(char *)"locale", (getter)app_translations_locale_get, NULL, app_translations_locale_doc, NULL},
489         {(char *)"locales", (getter)app_translations_locales_get, NULL, app_translations_locales_doc, NULL},
490         {NULL}
491 };
492
493 /* pgettext helper. */
494 static PyObject *_py_pgettext(PyObject *args, PyObject *kw, const char *(*_pgettext)(const char *, const char *))
495 {
496         static const char *kwlist[] = {"msgid", "msgctxt", NULL};
497
498 #ifdef WITH_INTERNATIONAL
499         char *msgid, *msgctxt = NULL;
500
501         if (!PyArg_ParseTupleAndKeywords(args, kw,
502                                          "s|z:bpy.app.translations.pgettext",
503                                          (char **)kwlist, &msgid, &msgctxt))
504         {
505                 return NULL;
506         }
507
508         return PyUnicode_FromString((*_pgettext)(msgctxt ? msgctxt : BLF_I18NCONTEXT_DEFAULT, msgid));
509 #else
510         PyObject *msgid, *msgctxt;
511         (void)_pgettext;
512
513         if (!PyArg_ParseTupleAndKeywords(args, kw,
514                                          "O|O:bpy.app.translations.pgettext",
515                                          (char **)kwlist, &msgid, &msgctxt))
516         {
517                 return NULL;
518         }
519
520         return Py_INCREF_RET(msgid);
521 #endif
522 }
523
524 PyDoc_STRVAR(app_translations_pgettext_doc,
525 ".. method:: pgettext(msgid, msgctxt)\n"
526 "\n"
527 "   Try to translate the given msgid (with optional msgctxt).\n"
528 "\n"
529 "   .. note::\n"
530 "       The ``(msgid, msgctxt)`` parameters order has been switched compared to gettext function, to allow\n"
531 "       single-parameter calls (context then defaults to BLF_I18NCONTEXT_DEFAULT).\n"
532 "\n"
533 "   .. note::\n"
534 "       You should really rarely need to use this function in regular addon code, as all translation should be\n"
535 "       handled by Blender internal code. The only exception are string containing formatting (like \"File: %r\"),\n"
536 "       but you should rather use :func:`pgettext_iface`/:func:`pgettext_tip` in those cases!\n"
537 "\n"
538 "   .. note::\n"
539 "       Does nothing when Blender is built without internationalization support (hence always returns ``msgid``).\n"
540 "\n"
541 "   :arg msgid: The string to translate.\n"
542 "   :type msgid: string\n"
543 "   :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
544 "   :type msgctxt: string or None\n"
545 "   :return: The translated string (or msgid if no translation was found).\n"
546 "\n"
547 );
548 static PyObject *app_translations_pgettext(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
549 {
550         return _py_pgettext(args, kw, BLF_pgettext);
551 }
552
553 PyDoc_STRVAR(app_translations_pgettext_iface_doc,
554 ".. method:: pgettext_iface(msgid, msgctxt)\n"
555 "\n"
556 "   Try to translate the given msgid (with optional msgctxt), if labels' translation is enabled.\n"
557 "\n"
558 "   .. note::\n"
559 "       See :func:`pgettext` notes.\n"
560 "\n"
561 "   :arg msgid: The string to translate.\n"
562 "   :type msgid: string\n"
563 "   :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
564 "   :type msgctxt: string or None\n"
565 "   :return: The translated string (or msgid if no translation was found).\n"
566 "\n"
567 );
568 static PyObject *app_translations_pgettext_iface(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
569 {
570         return _py_pgettext(args, kw, BLF_translate_do_iface);
571 }
572
573 PyDoc_STRVAR(app_translations_pgettext_tip_doc,
574 ".. method:: pgettext_tip(msgid, msgctxt)\n"
575 "\n"
576 "   Try to translate the given msgid (with optional msgctxt), if tooltips' translation is enabled.\n"
577 "\n"
578 "   .. note::\n"
579 "       See :func:`pgettext` notes.\n"
580 "\n"
581 "   :arg msgid: The string to translate.\n"
582 "   :type msgid: string\n"
583 "   :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
584 "   :type msgctxt: string or None\n"
585 "   :return: The translated string (or msgid if no translation was found).\n"
586 "\n"
587 );
588 static PyObject *app_translations_pgettext_tip(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
589 {
590         return _py_pgettext(args, kw, BLF_translate_do_tooltip);
591 }
592
593 PyDoc_STRVAR(app_translations_pgettext_data_doc,
594 ".. method:: pgettext_data(msgid, msgctxt)\n"
595 "\n"
596 "   Try to translate the given msgid (with optional msgctxt), if new data name's translation is enabled.\n"
597 "\n"
598 "   .. note::\n"
599 "       See :func:`pgettext` notes.\n"
600 "\n"
601 "   :arg msgid: The string to translate.\n"
602 "   :type msgid: string\n"
603 "   :arg msgctxt: The translation context (defaults to BLF_I18NCONTEXT_DEFAULT).\n"
604 "   :type msgctxt: string or None\n"
605 "   :return: The translated string (or ``msgid`` if no translation was found).\n"
606 "\n"
607 );
608 static PyObject *app_translations_pgettext_data(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
609 {
610         return _py_pgettext(args, kw, BLF_translate_do_new_dataname);
611 }
612
613 PyDoc_STRVAR(app_translations_locale_explode_doc,
614 ".. method:: locale_explode(locale)\n"
615 "\n"
616 "   Return all components and their combinations  of the given ISO locale string.\n"
617 "\n"
618 "   >>> bpy.app.translations.locale_explode(\"sr_RS@latin\")\n"
619 "   (\"sr\", \"RS\", \"latin\", \"sr_RS\", \"sr@latin\")\n"
620 "\n"
621 "   For non-complete locales, missing elements will be None.\n"
622 "\n"
623 "   :arg locale: The ISO locale string to explode.\n"
624 "   :type msgid: string\n"
625 "   :return: A tuple ``(language, country, variant, language_country, language@variant)``.\n"
626 "\n"
627 );
628 static PyObject *app_translations_locale_explode(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
629 {
630         PyObject *ret_tuple;
631         static const char *kwlist[] = {"locale", NULL};
632         const char *locale;
633         char *language, *country, *variant, *language_country, *language_variant;
634
635         if (!PyArg_ParseTupleAndKeywords(args, kw, "s:bpy.app.translations.locale_explode", (char **)kwlist, &locale)) {
636                 return NULL;
637         }
638
639         BLF_locale_explode(locale, &language, &country, &variant, &language_country, &language_variant);
640
641         ret_tuple = Py_BuildValue("sssss", language, country, variant, language_country, language_variant);
642
643         MEM_SAFE_FREE(language);
644         MEM_SAFE_FREE(country);
645         MEM_SAFE_FREE(variant);
646         MEM_SAFE_FREE(language_country);
647         MEM_SAFE_FREE(language_variant);
648
649         return ret_tuple;
650 }
651
652 static PyMethodDef app_translations_methods[] = {
653         /* Can't use METH_KEYWORDS alone, see http://bugs.python.org/issue11587 */
654         {"register", (PyCFunction)app_translations_py_messages_register, METH_VARARGS | METH_KEYWORDS,
655                       app_translations_py_messages_register_doc},
656         {"unregister", (PyCFunction)app_translations_py_messages_unregister, METH_VARARGS | METH_KEYWORDS,
657                         app_translations_py_messages_unregister_doc},
658         {"pgettext", (PyCFunction)app_translations_pgettext, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
659                       app_translations_pgettext_doc},
660         {"pgettext_iface", (PyCFunction)app_translations_pgettext_iface, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
661                             app_translations_pgettext_iface_doc},
662         {"pgettext_tip", (PyCFunction)app_translations_pgettext_tip, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
663                           app_translations_pgettext_tip_doc},
664         {"pgettext_data", (PyCFunction)app_translations_pgettext_data, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
665                            app_translations_pgettext_data_doc},
666         {"locale_explode", (PyCFunction)app_translations_locale_explode, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
667                             app_translations_locale_explode_doc},
668         {NULL}
669 };
670
671 static PyObject *app_translations_new(PyTypeObject *type, PyObject *UNUSED(args), PyObject *UNUSED(kw))
672 {
673 /*      printf("%s (%p)\n", __func__, _translations); */
674
675         if (!_translations) {
676                 _translations = (BlenderAppTranslations *)type->tp_alloc(type, 0);
677                 if (_translations) {
678                         PyObject *py_ctxts;
679                         BLF_i18n_contexts_descriptor *ctxt;
680
681                         _translations->contexts = app_translations_contexts_make();
682
683                         py_ctxts = PyDict_New();
684                         for (ctxt = _contexts; ctxt->c_id; ctxt++) {
685                                 PyObject *val = PyUnicode_FromString(ctxt->py_id);
686                                 PyDict_SetItemString(py_ctxts, ctxt->c_id, val);
687                                 Py_DECREF(val);
688                         }
689                         _translations->contexts_C_to_py = PyDictProxy_New(py_ctxts);
690                         Py_DECREF(py_ctxts);  /* The actual dict is only owned by its proxy */
691
692                         _translations->py_messages = PyDict_New();
693                 }
694         }
695
696         return (PyObject *)_translations;
697 }
698
699 static void app_translations_free(void *obj)
700 {
701         PyObject_Del(obj);
702 #ifdef WITH_INTERNATIONAL
703         _clear_translations_cache();
704 #endif
705 }
706
707 PyDoc_STRVAR(app_translations_doc,
708 "This object contains some data/methods regarding internationalization in Blender, and allows every py script\n"
709 "to feature translations for its own UI messages.\n"
710 "\n"
711 );
712 static PyTypeObject BlenderAppTranslationsType = {
713         PyVarObject_HEAD_INIT(NULL, 0)
714                                     /* tp_name */
715         "bpy.app._translations_type",
716                                     /* tp_basicsize */
717         sizeof(BlenderAppTranslations),
718         0,                          /* tp_itemsize */
719         /* methods */
720         /* No destructor, this is a singleton! */
721         NULL,                       /* tp_dealloc */
722         NULL,                       /* printfunc tp_print; */
723         NULL,                       /* getattrfunc tp_getattr; */
724         NULL,                       /* setattrfunc tp_setattr; */
725         NULL,                       /* tp_compare */ /* DEPRECATED in python 3.0! */
726         NULL,                       /* tp_repr */
727
728         /* Method suites for standard classes */
729         NULL,                       /* PyNumberMethods *tp_as_number; */
730         NULL,                       /* PySequenceMethods *tp_as_sequence; */
731         NULL,                       /* PyMappingMethods *tp_as_mapping; */
732
733         /* More standard operations (here for binary compatibility) */
734         NULL,                       /* hashfunc tp_hash; */
735         NULL,                       /* ternaryfunc tp_call; */
736         NULL,                       /* reprfunc tp_str; */
737         NULL,                       /* getattrofunc tp_getattro; */
738         NULL,                       /* setattrofunc tp_setattro; */
739
740         /* Functions to access object as input/output buffer */
741         NULL,                       /* PyBufferProcs *tp_as_buffer; */
742
743         /*** Flags to define presence of optional/expanded features ***/
744         Py_TPFLAGS_DEFAULT,         /* long tp_flags; */
745
746         app_translations_doc,       /* char *tp_doc;  Documentation string */
747
748         /*** Assigned meaning in release 2.0 ***/
749         /* call function for all accessible objects */
750         NULL,                       /* traverseproc tp_traverse; */
751
752         /* delete references to contained objects */
753         NULL,                       /* inquiry tp_clear; */
754
755         /***  Assigned meaning in release 2.1 ***/
756         /*** rich comparisons ***/
757         NULL,                       /* richcmpfunc tp_richcompare; */
758
759         /***  weak reference enabler ***/
760         0,                          /* long tp_weaklistoffset */
761
762         /*** Added in release 2.2 ***/
763         /*   Iterators */
764         NULL,                       /* getiterfunc tp_iter; */
765         NULL,                       /* iternextfunc tp_iternext; */
766
767         /*** Attribute descriptor and subclassing stuff ***/
768         app_translations_methods,   /* struct PyMethodDef *tp_methods; */
769         app_translations_members,   /* struct PyMemberDef *tp_members; */
770         app_translations_getseters, /* struct PyGetSetDef *tp_getset; */
771         NULL,                       /* struct _typeobject *tp_base; */
772         NULL,                       /* PyObject *tp_dict; */
773         NULL,                       /* descrgetfunc tp_descr_get; */
774         NULL,                       /* descrsetfunc tp_descr_set; */
775         0,                          /* long tp_dictoffset; */
776         NULL,                       /* initproc tp_init; */
777         NULL,                       /* allocfunc tp_alloc; */
778                                     /* newfunc tp_new; */
779         (newfunc)app_translations_new,
780         /*  Low-level free-memory routine */
781         app_translations_free,      /* freefunc tp_free;  */
782         /* For PyObject_IS_GC */
783         NULL,                       /* inquiry tp_is_gc;  */
784         NULL,                       /* PyObject *tp_bases; */
785         /* method resolution order */
786         NULL,                       /* PyObject *tp_mro;  */
787         NULL,                       /* PyObject *tp_cache; */
788         NULL,                       /* PyObject *tp_subclasses; */
789         NULL,                       /* PyObject *tp_weaklist; */
790         NULL
791 };
792
793 PyObject *BPY_app_translations_struct(void)
794 {
795         PyObject *ret;
796
797         /* Let's finalize our contexts structseq definition! */
798         {
799                 BLF_i18n_contexts_descriptor *ctxt;
800                 PyStructSequence_Field *desc;
801
802                 /* We really populate the contexts' fields here! */
803                 for (ctxt = _contexts, desc = app_translations_contexts_desc.fields; ctxt->c_id; ctxt++, desc++) {
804                         desc->name = (char *)ctxt->py_id;
805                         desc->doc = NULL;
806                 }
807                 desc->name = desc->doc = NULL;  /* End sentinel! */
808
809                 PyStructSequence_InitType(&BlenderAppTranslationsContextsType, &app_translations_contexts_desc);
810         }
811
812         if (PyType_Ready(&BlenderAppTranslationsType) < 0)
813                 return NULL;
814
815         ret = PyObject_CallObject((PyObject *)&BlenderAppTranslationsType, NULL);
816
817         /* prevent user from creating new instances */
818         BlenderAppTranslationsType.tp_new = NULL;
819         /* without this we can't do set(sys.modules) [#29635] */
820         BlenderAppTranslationsType.tp_hash = (hashfunc)_Py_HashPointer;
821
822         return ret;
823 }