diff options
Diffstat (limited to 'docs/programmer_reference/program_i18n.html')
| -rw-r--r-- | docs/programmer_reference/program_i18n.html | 302 |
1 files changed, 302 insertions, 0 deletions
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 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <title>Globalization Support</title> + <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> + <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> + <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> + <link rel="up" href="program.html" title="Chapter 15. Programmer Notes" /> + <link rel="prev" href="program_errorret.html" title="Error returns to applications" /> + <link rel="next" href="program_environ.html" title="Environment variables" /> + </head> + <body> + <div xmlns="" class="navheader"> + <div class="libver"> + <p>Library Version 12.1.6.1</p> + </div> + <table width="100%" summary="Navigation header"> + <tr> + <th colspan="3" align="center">Globalization Support</th> + </tr> + <tr> + <td width="20%" align="left"><a accesskey="p" href="program_errorret.html">Prev</a> </td> + <th width="60%" align="center">Chapter 15. Programmer Notes </th> + <td width="20%" align="right"> <a accesskey="n" href="program_environ.html">Next</a></td> + </tr> + </table> + <hr /> + </div> + <div class="sect1" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h2 class="title" style="clear: both"><a id="program_i18n"></a>Globalization Support</h2> + </div> + </div> + </div> + <div class="toc"> + <dl> + <dt> + <span class="sect2"> + <a href="program_i18n.html#idp2473976">Message Format</a> + </span> + </dt> + <dt> + <span class="sect2"> + <a href="program_i18n.html#idp2493888">Enable Globalization Support</a> + </span> + </dt> + <dt> + <span class="sect2"> + <a href="program_i18n.html#localization_example">Localization Example</a> + </span> + </dt> + </dl> + </div> + <p> + 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 <span> + <a class="ulink" href="http://docs.oracle.com/cd/E17076_02/html/articles/mssgtxt/index.html" target="_top">Berkeley DB Message Reference Guide</a>. + </span> + + </p> + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a id="idp2473976"></a>Message Format</h3> + </div> + </div> + </div> + <p> + By default, Berkeley DB messages are comprised of a + message number followed by message text in English. For + example: + </p> + <pre class="programlisting">BDB1001 illegal record number size</pre> + <p> + 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. + </p> + <p> + If localization is enabled, the translated message is + substituted for the original message text. + </p> + </div> + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a id="idp2493888"></a>Enable Globalization Support</h3> + </div> + </div> + </div> + <p> + To output messages in a language other than the default + English, follow the steps below: + </p> + <div class="orderedlist"> + <ol type="1"> + <li> + <p> + 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. + </p> + </li> + <li> + <p> + Add the name of the localization function as + the prefix for "(msg)" when + <code class="literal">HAVE_LOCALIZATION</code> is + defined in <code class="literal">build_unix/db_int.in</code> + on *nux, or in + <code class="literal">build_windows/db_int.h</code> on + Windows. + </p> + </li> + <li> + <p> + On *nix, specify + <code class="literal">-DHAVE_LOCALIZATION</code> to + CFLAGS. On Windows, specify <code class="literal">/D + HAVE_LOCALIZATION</code> to the + <code class="literal">C/C++ Additional Options</code> in + the db project properties. + </p> + </li> + <li> + <p> + Within your application code, use + <a href="../api_reference/C/envset_errcall.html" class="olink">DB_ENV->set_errcall()</a> or <a href="../api_reference/C/dbset_errcall.html" class="olink">DB->set_errcall()</a> to print the + messages. + </p> + </li> + </ol> + </div> + <p> + 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 <a href="../api_reference/C/envset_errcall.html" class="olink">DB_ENV->set_errcall()</a> + or <a href="../api_reference/C/dbset_errcall.html" class="olink">DB->set_errcall()</a> can be used to revert the UTF-8 Unicode + back to the UTF-16 Unicode. + </p> + </div> + <div class="sect2" lang="en" xml:lang="en"> + <div class="titlepage"> + <div> + <div> + <h3 class="title"><a id="localization_example"></a>Localization Example</h3> + </div> + </div> + </div> + <p> + The following example walks you through providing + localization support for a single Berkeley DB error + message: + </p> + <div class="itemizedlist"> + <ul type="disc"> + <li> + <p> + Make the resource bundles. These provide the + actual text translation: + </p> + <p> + es.txt: + </p> + <pre class="programlisting">es { +BDB1002 illegal record number of 0 {"BDB1002 illegal record number of 0"} +} </pre> + <p> + de_CH.txt: + </p> + <pre class="programlisting">de_CH { +BDB1002 illegal record number of 0 {"BDB1002 illegale Rekordzahl von 0"} +} </pre> + <p> + root.txt: + </p> + <pre class="programlisting">root { +BDB1002 illegal record number of 0 {"BDB1002 illegal record number of 0"} +} </pre> + </li> + <li> + <p> + Write and compile your localization functions: + Note that the "es", "de_CH" and "root" tags are + used as the locale name in + <code class="literal">ures_open()</code>. + </p> + <p> + Also notice that because + <code class="literal">ures_getStringByKey()</code> + returns UTF-16 Unicode, its output is converted to + UTF-8 using <code class="literal">ucnv_fromUChars()</code>. + </p> + <pre class="programlisting">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); +} </pre> + </li> + <li> + <p> + Update <code class="literal">db_int.h</code> so that + <code class="literal">_(msg)</code> is defined to use + the <code class="literal">translate()</code> that we created + in the previous step. + </p> + <pre class="programlisting">#ifdef HAVE_LOCALIZATION +#define _(msg) translate(msg) +#else +#define _(msg) msg +#endif </pre> + </li> + <li> + <p> + Rebuild Berkeley DB, making sure to specify the + <code class="literal">HAVE_LOCALIZATION</code> compile + option. + </p> + </li> + <li> + <p> + Specify the error callback. + </p> + <pre class="programlisting">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); +} </pre> + </li> + </ul> + </div> + <p> + 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. + </p> + </div> + </div> + <div class="navfooter"> + <hr /> + <table width="100%" summary="Navigation footer"> + <tr> + <td width="40%" align="left"><a accesskey="p" href="program_errorret.html">Prev</a> </td> + <td width="20%" align="center"> + <a accesskey="u" href="program.html">Up</a> + </td> + <td width="40%" align="right"> <a accesskey="n" href="program_environ.html">Next</a></td> + </tr> + <tr> + <td width="40%" align="left" valign="top">Error returns to + applications </td> + <td width="20%" align="center"> + <a accesskey="h" href="index.html">Home</a> + </td> + <td width="40%" align="right" valign="top"> Environment variables</td> + </tr> + </table> + </div> + </body> +</html> |