From 780b92ada9afcf1d58085a83a0b9e6bc982203d1 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Tue, 17 Feb 2015 17:25:57 +0000 Subject: Imported from /home/lorry/working-area/delta_berkeleydb/db-6.1.23.tar.gz. --- docs/programmer_reference/program_i18n.html | 302 ++++++++++++++++++++++++++++ 1 file changed, 302 insertions(+) create mode 100644 docs/programmer_reference/program_i18n.html (limited to 'docs/programmer_reference/program_i18n.html') diff --git a/docs/programmer_reference/program_i18n.html b/docs/programmer_reference/program_i18n.html new file mode 100644 index 00000000..8ce738e8 --- /dev/null +++ b/docs/programmer_reference/program_i18n.html @@ -0,0 +1,302 @@ + + + + + + Globalization Support + + + + + + + + +
+
+

Library Version 12.1.6.1

+
+ + + + + + + + + +
Globalization Support
Prev Chapter 15.  Programmer Notes  Next
+
+
+
+
+
+
+

Globalization Support

+
+
+
+
+
+
+ + Message Format + +
+
+ + Enable Globalization Support + +
+
+ + Localization Example + +
+
+
+

+ Berkeley DB globalization support allows you to translate + error and informational message text to the language of your + choosing, and then use the translated text instead of the + default English text. This section describes Berkeley DB's + globalization support. Berkeley DB's error and informational + message text is captured in the + Berkeley DB Message Reference Guide. + + +

+
+
+
+
+

Message Format

+
+
+
+

+ By default, Berkeley DB messages are comprised of a + message number followed by message text in English. For + example: +

+ 
BDB1001 illegal record number size
+

+ It is possible to build Berkeley DB with stripped + messages. When messages are stripped, the message text is + removed from the library, leaving behind only the message + number. When building a stripped library, there is no + message text available so localization will not work. +

+

+ If localization is enabled, the translated message is + substituted for the original message text. +

+
+
+
+
+
+

Enable Globalization Support

+
+
+
+

+ To output messages in a language other than the default + English, follow the steps below: +

+
+
    +
  1. +

    + Provide an i18n component containing a + localization function used to translate messages, + and translation files that map existing messages + to localized messages. The localization function + can be added to the current Berkeley DB project, + or as a dynamic library that is called at run + time. +

    +
    2. +
  2. +

    + Add the name of the localization function as + the prefix for "(msg)" when + HAVE_LOCALIZATION is + defined in build_unix/db_int.in + on *nux, or in + build_windows/db_int.h on + Windows. +

    +
    3. +
  3. +

    + On *nix, specify + -DHAVE_LOCALIZATION to + CFLAGS. On Windows, specify /D + HAVE_LOCALIZATION to the + C/C++ Additional Options in + the db project properties. +

    +
    4. +
  4. +

    + Within your application code, use + DB_ENV->set_errcall() or DB->set_errcall() to print the + messages. +

    +
    5. +
+
+

+ Note that Berkeley DB supports only UTF-8 for its + message text. If your localization requires UTF-16 + Unicode, the UTF-16 characters must be converted to UTF-8 + Unicode by your localization function. If necessary, the + error reporting function you specify to DB_ENV->set_errcall() + or DB->set_errcall() can be used to revert the UTF-8 Unicode + back to the UTF-16 Unicode. +

+
+
+
+
+
+

Localization Example

+
+
+
+

+ The following example walks you through providing + localization support for a single Berkeley DB error + message: +

+
+
    +
  • +

    + Make the resource bundles. These provide the + actual text translation: +

    +

    + es.txt: +

    + 
    es {
+BDB1002 illegal record number of 0 {"BDB1002 illegal record number of 0"}
+}
    +

    + de_CH.txt: +

    + 
    de_CH {
+BDB1002 illegal record number of 0 {"BDB1002 illegale Rekordzahl von 0"}
+}
    +

    + root.txt: +

    + 
    root {
+BDB1002 illegal record number of 0 {"BDB1002 illegal record number of 0"}
+}
    +
    • +
  • +

    + Write and compile your localization functions: + Note that the "es", "de_CH" and "root" tags are + used as the locale name in + ures_open(). +

    +

    + Also notice that because + ures_getStringByKey() + returns UTF-16 Unicode, its output is converted to + UTF-8 using ucnv_fromUChars(). +

    + 
    UConverter *conv;
+UResourceBundle *rhandle;
+char *mbuf;
+
+initialize() {
+   /* Open ICU resource, specify the locale. */
+   rhandle = ures_open(resource, "de_CH", &status);
+   /* Open an ICU converter. */ 
+   conv = ucnv_open("iso-8859-3", &status);
+   mbuf = malloc(len * sizeof(char));
+   memset(mbuf, 0, 100 * sizeof(char));
+}
+
+translate() {
+   const UChar *wmsg;
+   /* Get the translated message from the resource. */
+   wmsg = ures_getStringByKey(rhandle, src, &len, &status);
+   /* Convert UChar * to char. */
+   len = ucnv_fromUChars(conv, wmsg, 100, , -1, &status);
+}
+
+close() {
+   ucnv_close(conv);
+   ures_close(rhandle);
+   free(mbuf);
+}
    +
    • +
  • +

    + Update db_int.h so that + _(msg) is defined to use + the translate() that we created + in the previous step. +

    + 
    #ifdef HAVE_LOCALIZATION
+#define _(msg)  translate(msg)
+#else
+#define _(msg)  msg
+#endif
    +
    • +
  • +

    + Rebuild Berkeley DB, making sure to specify the + HAVE_LOCALIZATION compile + option. +

    +
    • +
  • +

    + Specify the error callback. +

    + 
    dbp->set_errcall(dbp, print_err); 
+
+print_err() {
+   const UChar *wmsg;
+   len = ucnv_toUChars(conv, wmsg, 100, src, len, &status);
+   u_stdout = u_finit(stdout, NULL,  NULL);
+   u_file_write((UChar *)wmsg, len, u_stdout);
+}
    +
    • +
+
+

+ The result of this is if you input an incorrect recno + and reach the error 1002, the message "BDB1002 illegale + Rekordzahl von 0" is output. +

+
+
+
+
+ + + + + + + + + + + +
Prev  + Up +  Next
Error returns to + applications  + Home +  Environment variables
+
+ + -- cgit v1.2.1