Merge branch 'master' into blender2.8
[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 "BLT_translation.h"
45 #include "BLT_lang.h"
46
47 #include "RNA_types.h"
48
49 #include "../generic/python_utildefines.h"
50
51 typedef struct {
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(BLT_is_default_context(msgctxt) ? BLT_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         BLT_lang_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                                 const char *msgctxt = NULL, *msgid = NULL;
185                                 bool invalid_key = false;
186
187                                 if ((PyTuple_CheckExact(pykey) == false) || (PyTuple_GET_SIZE(pykey) != 2)) {
188                                         invalid_key = true;
189                                 }
190                                 else {
191                                         PyObject *tmp = PyTuple_GET_ITEM(pykey, 0);
192                                         if (tmp == Py_None) {
193                                                 msgctxt = BLT_I18NCONTEXT_DEFAULT_BPYRNA;
194                                         }
195                                         else if (PyUnicode_Check(tmp)) {
196                                                 msgctxt = _PyUnicode_AsString(tmp);
197                                         }
198                                         else {
199                                                 invalid_key = true;
200                                         }
201
202                                         tmp = PyTuple_GET_ITEM(pykey, 1);
203                                         if (PyUnicode_Check(tmp)) {
204                                                 msgid = _PyUnicode_AsString(tmp);
205                                         }
206                                         else {
207                                                 invalid_key = true;
208                                         }
209                                 }
210
211                                 if (invalid_key) {
212                                         printf("WARNING! In translations' dict of \"");
213                                         PyObject_Print(uuid, stdout, Py_PRINT_RAW);
214                                         printf("\", %s language:\n", locale);
215                                         printf("    Keys must be tuples of (msgctxt [string or None], msgid [string]), "
216                                                "this one is not valid, skipping: ");
217                                         PyObject_Print(pykey, stdout, Py_PRINT_RAW);
218                                         printf("\n");
219                                         continue;
220                                 }
221                                 if (PyUnicode_Check(trans) == false) {
222                                         printf("WARNING! In translations' dict of \"");
223                                         PyObject_Print(uuid, stdout, Py_PRINT_RAW);
224                                         printf("\":\n");
225                                         printf("    Values must be strings, this one is not valid, skipping: ");
226                                         PyObject_Print(trans, stdout, Py_PRINT_RAW);
227                                         printf("\n");
228                                         continue;
229                                 }
230
231                                 /* Do not overwrite existing keys! */
232                                 if (BPY_app_translations_py_pgettext(msgctxt, msgid) == msgid) {
233                                         GHashKey *key = _ghashutil_keyalloc(msgctxt, msgid);
234                                         BLI_ghash_insert(_translations_cache, key, BLI_strdup(_PyUnicode_AsString(trans)));
235                                 }
236                         }
237                 }
238         }
239
240         /* Clean up! */
241         MEM_SAFE_FREE(language);
242         MEM_SAFE_FREE(language_country);
243         MEM_SAFE_FREE(language_variant);
244 }
245
246 const char *BPY_app_translations_py_pgettext(const char *msgctxt, const char *msgid)
247 {
248 #define STATIC_LOCALE_SIZE 32  /* Should be more than enough! */
249
250         GHashKey key;
251         static char locale[STATIC_LOCALE_SIZE] = "";
252         const char *tmp;
253
254         /* Just in case, should never happen! */
255         if (!_translations)
256                 return msgid;
257
258         tmp = BLT_lang_get();
259         if (!STREQ(tmp, locale) || !_translations_cache) {
260                 PyGILState_STATE _py_state;
261
262                 BLI_strncpy(locale, tmp, STATIC_LOCALE_SIZE);
263
264                 /* Locale changed or cache does not exist, refresh the whole cache! */
265                 /* This func may be called from C (i.e. outside of python interpreter 'context'). */
266                 _py_state = PyGILState_Ensure();
267
268                 _build_translations_cache(_translations->py_messages, locale);
269
270                 PyGILState_Release(_py_state);
271         }
272
273         /* And now, simply create the key (context, messageid) and find it in the cached dict! */
274         key.msgctxt = BLT_is_default_context(msgctxt) ? BLT_I18NCONTEXT_DEFAULT_BPYRNA : msgctxt;
275         key.msgid = msgid;
276
277         tmp = BLI_ghash_lookup(_translations_cache, &key);
278
279         return tmp ? tmp : msgid;
280
281 #undef STATIC_LOCALE_SIZE
282 }
283
284 #endif  /* WITH_INTERNATIONAL */
285
286 PyDoc_STRVAR(app_translations_py_messages_register_doc,
287 ".. method:: register(module_name, translations_dict)\n"
288 "\n"
289 "   Registers an addon's UI translations.\n"
290 "\n"
291 "   .. note::\n"
292 "       Does nothing when Blender is built without internationalization support.\n"
293 "\n"
294 "   :arg module_name: The name identifying the addon.\n"
295 "   :type module_name: string\n"
296 "   :arg translations_dict: A dictionary built like that:\n"
297 "       ``{locale: {msg_key: msg_translation, ...}, ...}``\n"
298 "   :type translations_dict: dict\n"
299 "\n"
300 );
301 static PyObject *app_translations_py_messages_register(BlenderAppTranslations *self, PyObject *args, PyObject *kw)
302 {
303 #ifdef WITH_INTERNATIONAL
304         static const char *kwlist[] = {"module_name", "translations_dict", NULL};
305         PyObject *module_name, *uuid_dict;
306
307         if (!PyArg_ParseTupleAndKeywords(args, kw, "O!O!:bpy.app.translations.register", (char **)kwlist, &PyUnicode_Type,
308                                          &module_name, &PyDict_Type, &uuid_dict))
309         {
310                 return NULL;
311         }
312
313         if (PyDict_Contains(self->py_messages, module_name)) {
314                 PyErr_Format(PyExc_ValueError,
315                              "bpy.app.translations.register: translations message cache already contains some data for "
316                              "addon '%s'", (const char *)_PyUnicode_AsString(module_name));
317                 return NULL;
318         }
319
320         PyDict_SetItem(self->py_messages, module_name, uuid_dict);
321
322         /* Clear cached messages dict! */
323         _clear_translations_cache();
324 #else
325         (void)self;
326         (void)args;
327         (void)kw;
328 #endif
329
330         /* And we are done! */
331         Py_RETURN_NONE;
332 }
333
334 PyDoc_STRVAR(app_translations_py_messages_unregister_doc,
335 ".. method:: unregister(module_name)\n"
336 "\n"
337 "   Unregisters an addon's UI translations.\n"
338 "\n"
339 "   .. note::\n"
340 "       Does nothing when Blender is built without internationalization support.\n"
341 "\n"
342 "   :arg module_name: The name identifying the addon.\n"
343 "   :type module_name: string\n"
344 "\n"
345 );
346 static PyObject *app_translations_py_messages_unregister(BlenderAppTranslations *self, PyObject *args, PyObject *kw)
347 {
348 #ifdef WITH_INTERNATIONAL
349         static const char *kwlist[] = {"module_name", NULL};
350         PyObject *module_name;
351
352         if (!PyArg_ParseTupleAndKeywords(args, kw, "O!:bpy.app.translations.unregister", (char **)kwlist, &PyUnicode_Type,
353                                          &module_name))
354         {
355                 return NULL;
356         }
357
358         if (PyDict_Contains(self->py_messages, module_name)) {
359                 PyDict_DelItem(self->py_messages, module_name);
360                 /* Clear cached messages ghash! */
361                 _clear_translations_cache();
362         }
363 #else
364         (void)self;
365         (void)args;
366         (void)kw;
367 #endif
368
369         /* And we are done! */
370         Py_RETURN_NONE;
371 }
372
373 /***** C-defined contexts *****/
374 /* This is always available (even when WITH_INTERNATIONAL is not defined). */
375
376 static PyTypeObject BlenderAppTranslationsContextsType;
377
378 static BLT_i18n_contexts_descriptor _contexts[] = BLT_I18NCONTEXTS_DESC;
379
380 /* These fields are just empty placeholders, actual values get set in app_translations_struct().
381  * This allows us to avoid many handwriting, and above all, to keep all context definition stuff in BLT_translation.h!
382  */
383 static PyStructSequence_Field
384 app_translations_contexts_fields[ARRAY_SIZE(_contexts)] = {{NULL}};
385
386 static PyStructSequence_Desc app_translations_contexts_desc = {
387         (char *)"bpy.app.translations.contexts",     /* name */
388         (char *)"This named tuple contains all pre-defined translation contexts",    /* doc */
389         app_translations_contexts_fields,    /* fields */
390         ARRAY_SIZE(app_translations_contexts_fields) - 1
391 };
392
393 static PyObject *app_translations_contexts_make(void)
394 {
395         PyObject *translations_contexts;
396         BLT_i18n_contexts_descriptor *ctxt;
397         int pos = 0;
398
399         translations_contexts = PyStructSequence_New(&BlenderAppTranslationsContextsType);
400         if (translations_contexts == NULL) {
401                 return NULL;
402         }
403
404 #define SetObjString(item) PyStructSequence_SET_ITEM(translations_contexts, pos++, PyUnicode_FromString((item)))
405 #define SetObjNone() PyStructSequence_SET_ITEM(translations_contexts, pos++, Py_INCREF_RET(Py_None))
406
407         for (ctxt = _contexts; ctxt->c_id; ctxt++) {
408                 if (ctxt->value) {
409                         SetObjString(ctxt->value);
410                 }
411                 else {
412                         SetObjNone();
413                 }
414         }
415
416 #undef SetObjString
417 #undef SetObjNone
418
419         return translations_contexts;
420 }
421
422 /***** Main BlenderAppTranslations Py object definition *****/
423
424 PyDoc_STRVAR(app_translations_contexts_doc,
425 "A named tuple containing all pre-defined translation contexts.\n"
426 "\n"
427 ".. warning::\n"
428 "    Never use a (new) context starting with \"" BLT_I18NCONTEXT_DEFAULT_BPYRNA "\", it would be internally \n"
429 "    assimilated as the default one!\n"
430 );
431
432 PyDoc_STRVAR(app_translations_contexts_C_to_py_doc,
433         "A readonly dict mapping contexts' C-identifiers to their py-identifiers."
434 );
435
436 static PyMemberDef app_translations_members[] = {
437         {(char *)"contexts", T_OBJECT_EX, offsetof(BlenderAppTranslations, contexts), READONLY,
438                              app_translations_contexts_doc},
439         {(char *)"contexts_C_to_py", T_OBJECT_EX, offsetof(BlenderAppTranslations, contexts_C_to_py), READONLY,
440                                      app_translations_contexts_C_to_py_doc},
441         {NULL}
442 };
443
444 PyDoc_STRVAR(app_translations_locale_doc,
445 "The actual locale currently in use (will always return a void string when Blender is built without "
446 "internationalization support)."
447 );
448 static PyObject *app_translations_locale_get(PyObject *UNUSED(self), void *UNUSED(userdata))
449 {
450         return PyUnicode_FromString(BLT_lang_get());
451 }
452
453 /* Note: defining as getter, as (even if quite unlikely), this *may* change during runtime... */
454 PyDoc_STRVAR(app_translations_locales_doc, "All locales currently known by Blender (i.e. available as translations).");
455 static PyObject *app_translations_locales_get(PyObject *UNUSED(self), void *UNUSED(userdata))
456 {
457         PyObject *ret;
458         EnumPropertyItem *it, *items = BLT_lang_RNA_enum_properties();
459         int num_locales = 0, pos = 0;
460
461         if (items) {
462                 /* This is not elegant, but simple! */
463                 for (it = items; it->identifier; it++) {
464                         if (it->value)
465                                 num_locales++;
466                 }
467         }
468
469         ret = PyTuple_New(num_locales);
470
471         if (items) {
472                 for (it = items; it->identifier; it++) {
473                         if (it->value)
474                                 PyTuple_SET_ITEM(ret, pos++, PyUnicode_FromString(it->description));
475                 }
476         }
477
478         return ret;
479 }
480
481 static PyGetSetDef app_translations_getseters[] = {
482         /* {name, getter, setter, doc, userdata} */
483         {(char *)"locale", (getter)app_translations_locale_get, NULL, app_translations_locale_doc, NULL},
484         {(char *)"locales", (getter)app_translations_locales_get, NULL, app_translations_locales_doc, NULL},
485         {NULL}
486 };
487
488 /* pgettext helper. */
489 static PyObject *_py_pgettext(PyObject *args, PyObject *kw, const char *(*_pgettext)(const char *, const char *))
490 {
491         static const char *kwlist[] = {"msgid", "msgctxt", NULL};
492
493 #ifdef WITH_INTERNATIONAL
494         char *msgid, *msgctxt = NULL;
495
496         if (!PyArg_ParseTupleAndKeywords(args, kw,
497                                          "s|z:bpy.app.translations.pgettext",
498                                          (char **)kwlist, &msgid, &msgctxt))
499         {
500                 return NULL;
501         }
502
503         return PyUnicode_FromString((*_pgettext)(msgctxt ? msgctxt : BLT_I18NCONTEXT_DEFAULT, msgid));
504 #else
505         PyObject *msgid, *msgctxt;
506         (void)_pgettext;
507
508         if (!PyArg_ParseTupleAndKeywords(args, kw,
509                                          "O|O:bpy.app.translations.pgettext",
510                                          (char **)kwlist, &msgid, &msgctxt))
511         {
512                 return NULL;
513         }
514
515         return Py_INCREF_RET(msgid);
516 #endif
517 }
518
519 PyDoc_STRVAR(app_translations_pgettext_doc,
520 ".. method:: pgettext(msgid, msgctxt)\n"
521 "\n"
522 "   Try to translate the given msgid (with optional msgctxt).\n"
523 "\n"
524 "   .. note::\n"
525 "       The ``(msgid, msgctxt)`` parameters order has been switched compared to gettext function, to allow\n"
526 "       single-parameter calls (context then defaults to BLT_I18NCONTEXT_DEFAULT).\n"
527 "\n"
528 "   .. note::\n"
529 "       You should really rarely need to use this function in regular addon code, as all translation should be\n"
530 "       handled by Blender internal code. The only exception are string containing formatting (like \"File: %r\"),\n"
531 "       but you should rather use :func:`pgettext_iface`/:func:`pgettext_tip` in those cases!\n"
532 "\n"
533 "   .. note::\n"
534 "       Does nothing when Blender is built without internationalization support (hence always returns ``msgid``).\n"
535 "\n"
536 "   :arg msgid: The string to translate.\n"
537 "   :type msgid: string\n"
538 "   :arg msgctxt: The translation context (defaults to BLT_I18NCONTEXT_DEFAULT).\n"
539 "   :type msgctxt: string or None\n"
540 "   :return: The translated string (or msgid if no translation was found).\n"
541 "\n"
542 );
543 static PyObject *app_translations_pgettext(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
544 {
545         return _py_pgettext(args, kw, BLT_pgettext);
546 }
547
548 PyDoc_STRVAR(app_translations_pgettext_iface_doc,
549 ".. method:: pgettext_iface(msgid, msgctxt)\n"
550 "\n"
551 "   Try to translate the given msgid (with optional msgctxt), if labels' translation is enabled.\n"
552 "\n"
553 "   .. note::\n"
554 "       See :func:`pgettext` notes.\n"
555 "\n"
556 "   :arg msgid: The string to translate.\n"
557 "   :type msgid: string\n"
558 "   :arg msgctxt: The translation context (defaults to BLT_I18NCONTEXT_DEFAULT).\n"
559 "   :type msgctxt: string or None\n"
560 "   :return: The translated string (or msgid if no translation was found).\n"
561 "\n"
562 );
563 static PyObject *app_translations_pgettext_iface(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
564 {
565         return _py_pgettext(args, kw, BLT_translate_do_iface);
566 }
567
568 PyDoc_STRVAR(app_translations_pgettext_tip_doc,
569 ".. method:: pgettext_tip(msgid, msgctxt)\n"
570 "\n"
571 "   Try to translate the given msgid (with optional msgctxt), if tooltips' translation is enabled.\n"
572 "\n"
573 "   .. note::\n"
574 "       See :func:`pgettext` notes.\n"
575 "\n"
576 "   :arg msgid: The string to translate.\n"
577 "   :type msgid: string\n"
578 "   :arg msgctxt: The translation context (defaults to BLT_I18NCONTEXT_DEFAULT).\n"
579 "   :type msgctxt: string or None\n"
580 "   :return: The translated string (or msgid if no translation was found).\n"
581 "\n"
582 );
583 static PyObject *app_translations_pgettext_tip(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
584 {
585         return _py_pgettext(args, kw, BLT_translate_do_tooltip);
586 }
587
588 PyDoc_STRVAR(app_translations_pgettext_data_doc,
589 ".. method:: pgettext_data(msgid, msgctxt)\n"
590 "\n"
591 "   Try to translate the given msgid (with optional msgctxt), if new data name's translation is enabled.\n"
592 "\n"
593 "   .. note::\n"
594 "       See :func:`pgettext` notes.\n"
595 "\n"
596 "   :arg msgid: The string to translate.\n"
597 "   :type msgid: string\n"
598 "   :arg msgctxt: The translation context (defaults to BLT_I18NCONTEXT_DEFAULT).\n"
599 "   :type msgctxt: string or None\n"
600 "   :return: The translated string (or ``msgid`` if no translation was found).\n"
601 "\n"
602 );
603 static PyObject *app_translations_pgettext_data(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
604 {
605         return _py_pgettext(args, kw, BLT_translate_do_new_dataname);
606 }
607
608 PyDoc_STRVAR(app_translations_locale_explode_doc,
609 ".. method:: locale_explode(locale)\n"
610 "\n"
611 "   Return all components and their combinations  of the given ISO locale string.\n"
612 "\n"
613 "   >>> bpy.app.translations.locale_explode(\"sr_RS@latin\")\n"
614 "   (\"sr\", \"RS\", \"latin\", \"sr_RS\", \"sr@latin\")\n"
615 "\n"
616 "   For non-complete locales, missing elements will be None.\n"
617 "\n"
618 "   :arg locale: The ISO locale string to explode.\n"
619 "   :type msgid: string\n"
620 "   :return: A tuple ``(language, country, variant, language_country, language@variant)``.\n"
621 "\n"
622 );
623 static PyObject *app_translations_locale_explode(BlenderAppTranslations *UNUSED(self), PyObject *args, PyObject *kw)
624 {
625         PyObject *ret_tuple;
626         static const char *kwlist[] = {"locale", NULL};
627         const char *locale;
628         char *language, *country, *variant, *language_country, *language_variant;
629
630         if (!PyArg_ParseTupleAndKeywords(args, kw, "s:bpy.app.translations.locale_explode", (char **)kwlist, &locale)) {
631                 return NULL;
632         }
633
634         BLT_lang_locale_explode(locale, &language, &country, &variant, &language_country, &language_variant);
635
636         ret_tuple = Py_BuildValue("sssss", language, country, variant, language_country, language_variant);
637
638         MEM_SAFE_FREE(language);
639         MEM_SAFE_FREE(country);
640         MEM_SAFE_FREE(variant);
641         MEM_SAFE_FREE(language_country);
642         MEM_SAFE_FREE(language_variant);
643
644         return ret_tuple;
645 }
646
647 static PyMethodDef app_translations_methods[] = {
648         /* Can't use METH_KEYWORDS alone, see http://bugs.python.org/issue11587 */
649         {"register", (PyCFunction)app_translations_py_messages_register, METH_VARARGS | METH_KEYWORDS,
650                       app_translations_py_messages_register_doc},
651         {"unregister", (PyCFunction)app_translations_py_messages_unregister, METH_VARARGS | METH_KEYWORDS,
652                         app_translations_py_messages_unregister_doc},
653         {"pgettext", (PyCFunction)app_translations_pgettext, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
654                       app_translations_pgettext_doc},
655         {"pgettext_iface", (PyCFunction)app_translations_pgettext_iface, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
656                             app_translations_pgettext_iface_doc},
657         {"pgettext_tip", (PyCFunction)app_translations_pgettext_tip, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
658                           app_translations_pgettext_tip_doc},
659         {"pgettext_data", (PyCFunction)app_translations_pgettext_data, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
660                            app_translations_pgettext_data_doc},
661         {"locale_explode", (PyCFunction)app_translations_locale_explode, METH_VARARGS | METH_KEYWORDS | METH_STATIC,
662                             app_translations_locale_explode_doc},
663         {NULL}
664 };
665
666 static PyObject *app_translations_new(PyTypeObject *type, PyObject *UNUSED(args), PyObject *UNUSED(kw))
667 {
668 /*      printf("%s (%p)\n", __func__, _translations); */
669
670         if (!_translations) {
671                 _translations = (BlenderAppTranslations *)type->tp_alloc(type, 0);
672                 if (_translations) {
673                         PyObject *py_ctxts;
674                         BLT_i18n_contexts_descriptor *ctxt;
675
676                         _translations->contexts = app_translations_contexts_make();
677
678                         py_ctxts = _PyDict_NewPresized(ARRAY_SIZE(_contexts));
679                         for (ctxt = _contexts; ctxt->c_id; ctxt++) {
680                                 PyObject *val = PyUnicode_FromString(ctxt->py_id);
681                                 PyDict_SetItemString(py_ctxts, ctxt->c_id, val);
682                                 Py_DECREF(val);
683                         }
684                         _translations->contexts_C_to_py = PyDictProxy_New(py_ctxts);
685                         Py_DECREF(py_ctxts);  /* The actual dict is only owned by its proxy */
686
687                         _translations->py_messages = PyDict_New();
688                 }
689         }
690
691         return (PyObject *)_translations;
692 }
693
694 static void app_translations_free(void *obj)
695 {
696         PyObject_Del(obj);
697 #ifdef WITH_INTERNATIONAL
698         _clear_translations_cache();
699 #endif
700 }
701
702 PyDoc_STRVAR(app_translations_doc,
703 "This object contains some data/methods regarding internationalization in Blender, and allows every py script\n"
704 "to feature translations for its own UI messages.\n"
705 "\n"
706 );
707 static PyTypeObject BlenderAppTranslationsType = {
708         PyVarObject_HEAD_INIT(NULL, 0)
709                                     /* tp_name */
710         "bpy.app._translations_type",
711                                     /* tp_basicsize */
712         sizeof(BlenderAppTranslations),
713         0,                          /* tp_itemsize */
714         /* methods */
715         /* No destructor, this is a singleton! */
716         NULL,                       /* tp_dealloc */
717         NULL,                       /* printfunc tp_print; */
718         NULL,                       /* getattrfunc tp_getattr; */
719         NULL,                       /* setattrfunc tp_setattr; */
720         NULL,                       /* tp_compare */ /* DEPRECATED in python 3.0! */
721         NULL,                       /* tp_repr */
722
723         /* Method suites for standard classes */
724         NULL,                       /* PyNumberMethods *tp_as_number; */
725         NULL,                       /* PySequenceMethods *tp_as_sequence; */
726         NULL,                       /* PyMappingMethods *tp_as_mapping; */
727
728         /* More standard operations (here for binary compatibility) */
729         NULL,                       /* hashfunc tp_hash; */
730         NULL,                       /* ternaryfunc tp_call; */
731         NULL,                       /* reprfunc tp_str; */
732         NULL,                       /* getattrofunc tp_getattro; */
733         NULL,                       /* setattrofunc tp_setattro; */
734
735         /* Functions to access object as input/output buffer */
736         NULL,                       /* PyBufferProcs *tp_as_buffer; */
737
738         /*** Flags to define presence of optional/expanded features ***/
739         Py_TPFLAGS_DEFAULT,         /* long tp_flags; */
740
741         app_translations_doc,       /* char *tp_doc;  Documentation string */
742
743         /*** Assigned meaning in release 2.0 ***/
744         /* call function for all accessible objects */
745         NULL,                       /* traverseproc tp_traverse; */
746
747         /* delete references to contained objects */
748         NULL,                       /* inquiry tp_clear; */
749
750         /***  Assigned meaning in release 2.1 ***/
751         /*** rich comparisons ***/
752         NULL,                       /* richcmpfunc tp_richcompare; */
753
754         /***  weak reference enabler ***/
755         0,                          /* long tp_weaklistoffset */
756
757         /*** Added in release 2.2 ***/
758         /*   Iterators */
759         NULL,                       /* getiterfunc tp_iter; */
760         NULL,                       /* iternextfunc tp_iternext; */
761
762         /*** Attribute descriptor and subclassing stuff ***/
763         app_translations_methods,   /* struct PyMethodDef *tp_methods; */
764         app_translations_members,   /* struct PyMemberDef *tp_members; */
765         app_translations_getseters, /* struct PyGetSetDef *tp_getset; */
766         NULL,                       /* struct _typeobject *tp_base; */
767         NULL,                       /* PyObject *tp_dict; */
768         NULL,                       /* descrgetfunc tp_descr_get; */
769         NULL,                       /* descrsetfunc tp_descr_set; */
770         0,                          /* long tp_dictoffset; */
771         NULL,                       /* initproc tp_init; */
772         NULL,                       /* allocfunc tp_alloc; */
773                                     /* newfunc tp_new; */
774         (newfunc)app_translations_new,
775         /*  Low-level free-memory routine */
776         app_translations_free,      /* freefunc tp_free;  */
777         /* For PyObject_IS_GC */
778         NULL,                       /* inquiry tp_is_gc;  */
779         NULL,                       /* PyObject *tp_bases; */
780         /* method resolution order */
781         NULL,                       /* PyObject *tp_mro;  */
782         NULL,                       /* PyObject *tp_cache; */
783         NULL,                       /* PyObject *tp_subclasses; */
784         NULL,                       /* PyObject *tp_weaklist; */
785         NULL
786 };
787
788 PyObject *BPY_app_translations_struct(void)
789 {
790         PyObject *ret;
791
792         /* Let's finalize our contexts structseq definition! */
793         {
794                 BLT_i18n_contexts_descriptor *ctxt;
795                 PyStructSequence_Field *desc;
796
797                 /* We really populate the contexts' fields here! */
798                 for (ctxt = _contexts, desc = app_translations_contexts_desc.fields; ctxt->c_id; ctxt++, desc++) {
799                         desc->name = (char *)ctxt->py_id;
800                         desc->doc = NULL;
801                 }
802                 desc->name = desc->doc = NULL;  /* End sentinel! */
803
804                 PyStructSequence_InitType(&BlenderAppTranslationsContextsType, &app_translations_contexts_desc);
805         }
806
807         if (PyType_Ready(&BlenderAppTranslationsType) < 0)
808                 return NULL;
809
810         ret = PyObject_CallObject((PyObject *)&BlenderAppTranslationsType, NULL);
811
812         /* prevent user from creating new instances */
813         BlenderAppTranslationsType.tp_new = NULL;
814         /* without this we can't do set(sys.modules) [#29635] */
815         BlenderAppTranslationsType.tp_hash = (hashfunc)_Py_HashPointer;
816
817         return ret;
818 }
819
820 void BPY_app_translations_end(void)
821 {
822         /* Incase the object remains in a module's namespace, see T44127. */
823 #ifdef WITH_INTERNATIONAL
824         _clear_translations_cache();
825 #endif
826 }
827