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