Edit File: api-i18n.html
<!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>Kitchen.i18n Module — kitchen 1.1.1 documentation</title> <link rel="stylesheet" href="_static/default.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: '1.1.1', COLLAPSE_INDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/underscore.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within kitchen 1.1.1 documentation" href="_static/opensearch.xml"/> <link rel="top" title="kitchen 1.1.1 documentation" href="index.html" /> <link rel="up" title="Kitchen API" href="api-overview.html" /> <link rel="next" title="Kitchen.text: unicode and utf8 and xml oh my!" href="api-text.html" /> <link rel="prev" title="Kitchen API" href="api-overview.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="api-text.html" title="Kitchen.text: unicode and utf8 and xml oh my!" accesskey="N">next</a> |</li> <li class="right" > <a href="api-overview.html" title="Kitchen API" accesskey="P">previous</a> |</li> <li><a href="index.html">kitchen 1.1.1 documentation</a> »</li> <li><a href="api-overview.html" accesskey="U">Kitchen API</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="module-kitchen.i18n"> <span id="kitchen-i18n-module"></span><h1>Kitchen.i18n Module<a class="headerlink" href="#module-kitchen.i18n" title="Permalink to this headline">¶</a></h1> <p><a class="reference internal" href="glossary.html#term-i18n"><em class="xref std std-term">I18N</em></a> is an important piece of any modern program. Unfortunately, setting up <a class="reference internal" href="glossary.html#term-i18n"><em class="xref std std-term">i18n</em></a> in your program is often a confusing process. The functions provided here aim to make the programming side of that a little easier.</p> <p>Most projects will be able to do something like this when they startup:</p> <div class="highlight-python"><div class="highlight"><pre><span class="c"># myprogram/__init__.py:</span> <span class="kn">import</span> <span class="nn">os</span> <span class="kn">import</span> <span class="nn">sys</span> <span class="kn">from</span> <span class="nn">kitchen.i18n</span> <span class="kn">import</span> <span class="n">easy_gettext_setup</span> <span class="n">_</span><span class="p">,</span> <span class="n">N_</span> <span class="o">=</span> <span class="n">easy_gettext_setup</span><span class="p">(</span><span class="s">'myprogram'</span><span class="p">,</span> <span class="n">localedirs</span><span class="o">=</span><span class="p">(</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">realpath</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">__file__</span><span class="p">)),</span> <span class="s">'locale'</span><span class="p">),</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">prefix</span><span class="p">,</span> <span class="s">'lib'</span><span class="p">,</span> <span class="s">'locale'</span><span class="p">)</span> <span class="p">))</span> </pre></div> </div> <p>Then, in other files that have strings that need translating:</p> <div class="highlight-python"><div class="highlight"><pre><span class="c"># myprogram/commands.py:</span> <span class="kn">from</span> <span class="nn">myprogram</span> <span class="kn">import</span> <span class="n">_</span><span class="p">,</span> <span class="n">N_</span> <span class="k">def</span> <span class="nf">print_usage</span><span class="p">():</span> <span class="k">print</span> <span class="n">_</span><span class="p">(</span><span class="s">u"""available commands are:</span> <span class="s"> --help Display help</span> <span class="s"> --version Display version of this program</span> <span class="s"> --bake-me-a-cake as fast as you can</span> <span class="s"> """</span><span class="p">)</span> <span class="k">def</span> <span class="nf">print_invitations</span><span class="p">(</span><span class="n">age</span><span class="p">):</span> <span class="k">print</span> <span class="n">_</span><span class="p">(</span><span class="s">'Please come to my party.'</span><span class="p">)</span> <span class="k">print</span> <span class="n">N_</span><span class="p">(</span><span class="s">'I will be turning </span><span class="si">%(age)s</span><span class="s"> year old'</span><span class="p">,</span> <span class="s">'I will be turning </span><span class="si">%(age)s</span><span class="s"> years old'</span><span class="p">,</span> <span class="n">age</span><span class="p">)</span> <span class="o">%</span> <span class="p">{</span><span class="s">'age'</span><span class="p">:</span> <span class="n">age</span><span class="p">}</span> </pre></div> </div> <p>See the documentation of <a class="reference internal" href="#kitchen.i18n.easy_gettext_setup" title="kitchen.i18n.easy_gettext_setup"><tt class="xref py py-func docutils literal"><span class="pre">easy_gettext_setup()</span></tt></a> and <a class="reference internal" href="#kitchen.i18n.get_translation_object" title="kitchen.i18n.get_translation_object"><tt class="xref py py-func docutils literal"><span class="pre">get_translation_object()</span></tt></a> for more details.</p> <blockquote> <div><div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a></dt> <dd>for details of how the python gettext facilities work</dd> <dt><a class="reference external" href="http://babel.edgewall.org">babel</a></dt> <dd>The babel module for in depth information on gettext, <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a>, and translating your app. babel provides some nice features for <a class="reference internal" href="glossary.html#term-i18n"><em class="xref std std-term">i18n</em></a> on top of <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a></dd> </dl> </div> </div></blockquote> <div class="section" id="functions"> <h2>Functions<a class="headerlink" href="#functions" title="Permalink to this headline">¶</a></h2> <p><a class="reference internal" href="#kitchen.i18n.easy_gettext_setup" title="kitchen.i18n.easy_gettext_setup"><tt class="xref py py-func docutils literal"><span class="pre">easy_gettext_setup()</span></tt></a> should satisfy the needs of most users. <a class="reference internal" href="#kitchen.i18n.get_translation_object" title="kitchen.i18n.get_translation_object"><tt class="xref py py-func docutils literal"><span class="pre">get_translation_object()</span></tt></a> is designed to ease the way for anyone that needs more control.</p> <dl class="function"> <dt id="kitchen.i18n.easy_gettext_setup"> <tt class="descclassname">kitchen.i18n.</tt><tt class="descname">easy_gettext_setup</tt><big>(</big><em>domain</em>, <em>localedirs=()</em>, <em>use_unicode=True</em><big>)</big><a class="headerlink" href="#kitchen.i18n.easy_gettext_setup" title="Permalink to this definition">¶</a></dt> <dd><p>Setup translation functions for an application</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>domain</strong> – Name of the message domain. This should be a unique name that can be used to lookup the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a> for this app.</li> <li><strong>localedirs</strong> – Iterator of directories to look for <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> under. The first directory to exist is used regardless of whether messages for this domain are present. If none of the directories exist, fallback on <tt class="docutils literal"><span class="pre">sys.prefix</span></tt> + <tt class="file docutils literal"><span class="pre">/share/locale</span></tt> Default: No directories to search so we just use the fallback.</li> <li><strong>use_unicode</strong> – If <a class="reference external" href="http://docs.python.org/library/constants.html#True" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">True</span></tt></a> return the <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> functions for <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings else return the functions for byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> for the translations. Default is <a class="reference external" href="http://docs.python.org/library/constants.html#True" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">True</span></tt></a>.</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">tuple of the <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> function and <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> function for plurals</p> </td> </tr> </tbody> </table> <p>Setting up <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> can be a little tricky because of lack of documentation. This function will setup <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> using the <a class="reference external" href="http://docs.python.org/library/gettext.html#class-based-api">Class-based API</a> for you. For the simple case, you can use the default arguments and call it like this:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">_</span><span class="p">,</span> <span class="n">N_</span> <span class="o">=</span> <span class="n">easy_gettext_setup</span><span class="p">()</span> </pre></div> </div> <p>This will get you two functions, <tt class="xref py py-func docutils literal"><span class="pre">_()</span></tt> and <tt class="xref py py-func docutils literal"><span class="pre">N_()</span></tt> that you can use to mark strings in your code for translation. <tt class="xref py py-func docutils literal"><span class="pre">_()</span></tt> is used to mark strings that don’t need to worry about plural forms no matter what the value of the variable is. <tt class="xref py py-func docutils literal"><span class="pre">N_()</span></tt> is used to mark strings that do need to have a different form if a variable in the string is plural.</p> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference internal" href=""><em>Kitchen.i18n Module</em></a></dt> <dd>This module’s documentation has examples of using <tt class="xref py py-func docutils literal"><span class="pre">_()</span></tt> and <tt class="xref py py-func docutils literal"><span class="pre">N_()</span></tt></dd> <dt><a class="reference internal" href="#kitchen.i18n.get_translation_object" title="kitchen.i18n.get_translation_object"><tt class="xref py py-func docutils literal"><span class="pre">get_translation_object()</span></tt></a></dt> <dd>for information on how to use <tt class="xref py py-attr docutils literal"><span class="pre">localedirs</span></tt> to get the proper <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> both when in development and when installed to FHS compliant directories on Linux.</dd> </dl> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">The gettext functions returned from this function should be superior to the ones returned from <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a>. The traits that make them better are described in the <a class="reference internal" href="#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">DummyTranslations</span></tt></a> and <a class="reference internal" href="#kitchen.i18n.NewGNUTranslations" title="kitchen.i18n.NewGNUTranslations"><tt class="xref py py-class docutils literal"><span class="pre">NewGNUTranslations</span></tt></a> documentation.</p> </div> <p class="versionchanged"> <span class="versionmodified">Changed in version kitchen-0.2.4: </span>; API kitchen.i18n 2.0.0 Changed <a class="reference internal" href="#kitchen.i18n.easy_gettext_setup" title="kitchen.i18n.easy_gettext_setup"><tt class="xref py py-func docutils literal"><span class="pre">easy_gettext_setup()</span></tt></a> to return the lgettext functions instead of gettext functions when use_unicode=False.</p> </dd></dl> <dl class="function"> <dt id="kitchen.i18n.get_translation_object"> <tt class="descclassname">kitchen.i18n.</tt><tt class="descname">get_translation_object</tt><big>(</big><em>domain</em>, <em>localedirs=()</em>, <em>languages=None</em>, <em>class_=None</em>, <em>fallback=True</em>, <em>codeset=None</em><big>)</big><a class="headerlink" href="#kitchen.i18n.get_translation_object" title="Permalink to this definition">¶</a></dt> <dd><p>Get a translation object bound to the <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a></p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple"> <li><strong>domain</strong> – Name of the message domain. This should be a unique name that can be used to lookup the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a> for this app or library.</li> <li><strong>localedirs</strong> – Iterator of directories to look for <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> under. The directories are searched in order for <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a>. For each of the directories searched, we check for message catalogs in any language specified in:attr:<cite>languages</cite>. The <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> are used to create the Translation object that we return. The Translation object will attempt to lookup the msgid in the first catalog that we found. If it’s not in there, it will go through each subsequent catalog looking for a match. For this reason, the order in which you specify the <tt class="xref py py-attr docutils literal"><span class="pre">localedirs</span></tt> may be important. If no <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> are found, either return a <a class="reference internal" href="#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">DummyTranslations</span></tt></a> object or raise an <tt class="xref py py-exc docutils literal"><span class="pre">IOError</span></tt> depending on the value of <tt class="xref py py-attr docutils literal"><span class="pre">fallback</span></tt>. Rhe default localedir from <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> which is <tt class="file docutils literal"><span class="pre">os.path.join(sys.prefix,</span> <span class="pre">'share',</span> <span class="pre">'locale')</span></tt> on Unix is implicitly appended to the <tt class="xref py py-attr docutils literal"><span class="pre">localedirs</span></tt>, making it the last directory searched.</li> <li><strong>languages</strong> – <p>Iterator of language codes to check for <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a>. If unspecified, the user’s locale settings will be used.</p> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <p class="last"><a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.find" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">gettext.find()</span></tt></a> for information on what environment variables are used.</p> </div> </li> <li><strong>class</strong> – The class to use to extract translations from the <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a>. Defaults to <a class="reference internal" href="#kitchen.i18n.NewGNUTranslations" title="kitchen.i18n.NewGNUTranslations"><tt class="xref py py-class docutils literal"><span class="pre">NewGNUTranslations</span></tt></a>.</li> <li><strong>fallback</strong> – If set to data:<cite>False</cite>, raise an <tt class="xref py py-exc docutils literal"><span class="pre">IOError</span></tt> if no <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> are found. If <a class="reference external" href="http://docs.python.org/library/constants.html#True" title="(in Python v2.7)"><tt class="xref py py-data docutils literal"><span class="pre">True</span></tt></a>, the default, return a <a class="reference internal" href="#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">DummyTranslations</span></tt></a> object.</li> <li><strong>codeset</strong> – Set the character encoding to use when returning byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> objects. This is equivalent to calling <tt class="xref py py-meth docutils literal"><span class="pre">output_charset()</span></tt> on the Translations object that is returned from this function.</li> </ul> </td> </tr> <tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">Translation object to get <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> methods from</p> </td> </tr> </tbody> </table> <p>If you need more flexibility than <a class="reference internal" href="#kitchen.i18n.easy_gettext_setup" title="kitchen.i18n.easy_gettext_setup"><tt class="xref py py-func docutils literal"><span class="pre">easy_gettext_setup()</span></tt></a>, use this function. It sets up a <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> Translation object and returns it to you. Then you can access any of the methods of the object that you need directly. For instance, if you specifically need to access <tt class="xref py py-func docutils literal"><span class="pre">lgettext()</span></tt>:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">translations</span> <span class="o">=</span> <span class="n">get_translation_object</span><span class="p">(</span><span class="s">'foo'</span><span class="p">)</span> <span class="n">translations</span><span class="o">.</span><span class="n">lgettext</span><span class="p">(</span><span class="s">'My Message'</span><span class="p">)</span> </pre></div> </div> <p>This function is similar to the <a class="reference external" href="http://docs.python.org/library">python standard library</a> <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.translation" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">gettext.translation()</span></tt></a> but makes it better in two ways</p> <ol class="arabic"> <li><dl class="first docutils"> <dt>It returns <a class="reference internal" href="#kitchen.i18n.NewGNUTranslations" title="kitchen.i18n.NewGNUTranslations"><tt class="xref py py-class docutils literal"><span class="pre">NewGNUTranslations</span></tt></a> or <a class="reference internal" href="#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">DummyTranslations</span></tt></a></dt> <dd><p class="first last">objects by default. These are superior to the <tt class="xref py py-class docutils literal"><span class="pre">gettext.GNUTranslations</span></tt> and <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">gettext.NullTranslations</span></tt></a> objects because they are consistent in the string type they return and they fix several issues that can causethe <a class="reference external" href="http://docs.python.org/library">python standard library</a> objects to throw <tt class="xref py py-exc docutils literal"><span class="pre">UnicodeError</span></tt>.</p> </dd> </dl> </li> <li><dl class="first docutils"> <dt>This function takes multiple directories to search for</dt> <dd><p class="first last"><a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a>.</p> </dd> </dl> </li> </ol> <p>The latter is important when setting up <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> in a portable manner. There is not a common directory for translations across operating systems so one needs to look in multiple directories for the translations. <a class="reference internal" href="#kitchen.i18n.get_translation_object" title="kitchen.i18n.get_translation_object"><tt class="xref py py-func docutils literal"><span class="pre">get_translation_object()</span></tt></a> is able to handle that if you give it a list of directories to search for catalogs:</p> <div class="highlight-python"><div class="highlight"><pre><span class="n">translations</span> <span class="o">=</span> <span class="n">get_translation_object</span><span class="p">(</span><span class="s">'foo'</span><span class="p">,</span> <span class="n">localedirs</span><span class="o">=</span><span class="p">(</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">realpath</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">__file__</span><span class="p">)),</span> <span class="s">'locale'</span><span class="p">),</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">prefix</span><span class="p">,</span> <span class="s">'lib'</span><span class="p">,</span> <span class="s">'locale'</span><span class="p">)))</span> </pre></div> </div> <p>This will search for several different directories:</p> <ol class="arabic simple"> <li>A directory named <tt class="file docutils literal"><span class="pre">locale</span></tt> in the same directory as the module that called <a class="reference internal" href="#kitchen.i18n.get_translation_object" title="kitchen.i18n.get_translation_object"><tt class="xref py py-func docutils literal"><span class="pre">get_translation_object()</span></tt></a>,</li> <li>In <tt class="file docutils literal"><span class="pre">/usr/lib/locale</span></tt></li> <li>In <tt class="file docutils literal"><span class="pre">/usr/share/locale</span></tt> (the fallback directory)</li> </ol> <p>This allows <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> to work on Windows and in development (where the <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> are typically in the toplevel module directory) and also when installed under Linux (where the <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> are installed in <tt class="file docutils literal"><span class="pre">/usr/share/locale</span></tt>). You (or the system packager) just need to install the <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> in <tt class="file docutils literal"><span class="pre">/usr/share/locale</span></tt> and remove the <tt class="file docutils literal"><span class="pre">locale</span></tt> directory from the module to make this work. ie:</p> <div class="highlight-python"><pre>In development: ~/foo # Toplevel module directory ~/foo/__init__.py ~/foo/locale # With message catalogs below here: ~/foo/locale/es/LC_MESSAGES/foo.mo Installed on Linux: /usr/lib/python2.7/site-packages/foo /usr/lib/python2.7/site-packages/foo/__init__.py /usr/share/locale/ # With message catalogs below here: /usr/share/locale/es/LC_MESSAGES/foo.mo</pre> </div> <div class="admonition note"> <p class="first admonition-title">Note</p> <p class="last">This function will setup Translation objects that attempt to lookup msgids in all of the found <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a>. This means if you have several versions of the <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> installed in different directories that the function searches, you need to make sure that <tt class="xref py py-attr docutils literal"><span class="pre">localedirs</span></tt> specifies the directories so that newer <a class="reference internal" href="glossary.html#term-message-catalogs"><em class="xref std std-term">message catalogs</em></a> are searched first. It also means that if a newer catalog does not contain a translation for a msgid but an older one that’s in <tt class="xref py py-attr docutils literal"><span class="pre">localedirs</span></tt> does, the translation from that older catalog will be returned.</p> </div> <p class="versionchanged"> <span class="versionmodified">Changed in version kitchen-1.1.0: </span>; API kitchen.i18n 2.1.0 Add more parameters to <a class="reference internal" href="#kitchen.i18n.get_translation_object" title="kitchen.i18n.get_translation_object"><tt class="xref py py-func docutils literal"><span class="pre">get_translation_object()</span></tt></a> so it can more easily be used as a replacement for <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.translation" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">gettext.translation()</span></tt></a>. Also change the way we use localedirs. We cycle through them until we find a suitable locale file rather than simply cycling through until we find a directory that exists. The new code is based heavily on the <a class="reference external" href="http://docs.python.org/library">python standard library</a> <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.translation" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">gettext.translation()</span></tt></a> function.</p> </dd></dl> </div> <div class="section" id="translation-objects"> <h2>Translation Objects<a class="headerlink" href="#translation-objects" title="Permalink to this headline">¶</a></h2> <p>The standard translation objects from the <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> module suffer from several problems:</p> <ul class="simple"> <li>They can throw <tt class="xref py py-exc docutils literal"><span class="pre">UnicodeError</span></tt></li> <li>They can’t find translations for non-<a class="reference internal" href="glossary.html#term-ascii"><em class="xref std std-term">ASCII</em></a> byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> messages</li> <li>They may return either <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> from the same function even though the functions say they will only return <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> or only return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>.</li> </ul> <p><a class="reference internal" href="#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">DummyTranslations</span></tt></a> and <a class="reference internal" href="#kitchen.i18n.NewGNUTranslations" title="kitchen.i18n.NewGNUTranslations"><tt class="xref py py-class docutils literal"><span class="pre">NewGNUTranslations</span></tt></a> were written to fix these issues.</p> <dl class="class"> <dt id="kitchen.i18n.DummyTranslations"> <em class="property">class </em><tt class="descclassname">kitchen.i18n.</tt><tt class="descname">DummyTranslations</tt><big>(</big><em>fp=None</em><big>)</big><a class="headerlink" href="#kitchen.i18n.DummyTranslations" title="Permalink to this definition">¶</a></dt> <dd><p>Safer version of <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">gettext.NullTranslations</span></tt></a></p> <p>This Translations class doesn’t translate the strings and is intended to be used as a fallback when there were errors setting up a real Translations object. It’s safer than <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">gettext.NullTranslations</span></tt></a> in its handling of byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> vs <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings.</p> <p>Unlike <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">NullTranslations</span></tt></a>, this Translation class will never throw a <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.UnicodeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">UnicodeError</span></tt></a>. The code that you have around a call to <a class="reference internal" href="#kitchen.i18n.DummyTranslations" title="kitchen.i18n.DummyTranslations"><tt class="xref py py-class docutils literal"><span class="pre">DummyTranslations</span></tt></a> might throw a <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.UnicodeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">UnicodeError</span></tt></a> but at least that will be in code you control and can fix. Also, unlike <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">NullTranslations</span></tt></a> all of this Translation object’s methods guarantee to return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> except for <tt class="xref py py-meth docutils literal"><span class="pre">ugettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ungettext()</span></tt> which guarantee to return <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings.</p> <p>When byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> are returned, the strings will be encoded according to this algorithm:</p> <ol class="arabic simple"> <li>If a fallback has been added, the fallback will be called first. You’ll need to consult the fallback to see whether it performs any encoding changes.</li> <li>If a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> was given, the same byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> will be returned.</li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and <a class="reference internal" href="#kitchen.i18n.DummyTranslations.set_output_charset" title="kitchen.i18n.DummyTranslations.set_output_charset"><tt class="xref py py-meth docutils literal"><span class="pre">set_output_charset()</span></tt></a> has been called then we encode the string using the <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt></li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and this is <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt> and <tt class="xref py py-attr docutils literal"><span class="pre">_charset</span></tt> was set output in that charset.</li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and this is <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt> we encode it using ‘utf-8’.</li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and this is <tt class="xref py py-meth docutils literal"><span class="pre">lgettext()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">lngettext()</span></tt> we encode using the value of <a class="reference external" href="http://docs.python.org/library/locale.html#locale.getpreferredencoding" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">locale.getpreferredencoding()</span></tt></a></li> </ol> <p>For <tt class="xref py py-meth docutils literal"><span class="pre">ugettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ungettext()</span></tt>, we go through the same set of steps with the following differences:</p> <ul class="simple"> <li>We transform byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> into <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings for these methods.</li> <li>The encoding used to decode the byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> is taken from <a class="reference internal" href="#kitchen.i18n.DummyTranslations.input_charset" title="kitchen.i18n.DummyTranslations.input_charset"><tt class="xref py py-attr docutils literal"><span class="pre">input_charset</span></tt></a> if it’s set, otherwise we decode using <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a>.</li> </ul> <dl class="attribute"> <dt id="kitchen.i18n.DummyTranslations.input_charset"> <tt class="descname">input_charset</tt><a class="headerlink" href="#kitchen.i18n.DummyTranslations.input_charset" title="Permalink to this definition">¶</a></dt> <dd><p>is an extension to the <a class="reference external" href="http://docs.python.org/library">python standard library</a> <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> that specifies what charset a message is encoded in when decoding a message to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>. This is used for two purposes:</p> </dd></dl> <ol class="arabic simple"> <li>If the message string is a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>, this is used to decode the string to a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string before looking it up in the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a>.</li> <li>In <tt class="xref py py-meth docutils literal"><span class="pre">ugettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ungettext()</span></tt> methods, if a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> is given as the message and is untranslated this is used as the encoding when decoding to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>. This is different from <tt class="xref py py-attr docutils literal"><span class="pre">_charset</span></tt> which may be set when a <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a> is loaded because <a class="reference internal" href="#kitchen.i18n.DummyTranslations.input_charset" title="kitchen.i18n.DummyTranslations.input_charset"><tt class="xref py py-attr docutils literal"><span class="pre">input_charset</span></tt></a> is used to describe an encoding used in a python source file while <tt class="xref py py-attr docutils literal"><span class="pre">_charset</span></tt> describes the encoding used in the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a> file.</li> </ol> <p>Any characters that aren’t able to be transformed from a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or vice versa will be replaced with a replacement character (ie: <tt class="docutils literal"><span class="pre">u'�'</span></tt> in unicode based encodings, <tt class="docutils literal"><span class="pre">'?'</span></tt> in other <a class="reference internal" href="glossary.html#term-ascii"><em class="xref std std-term">ASCII</em></a> compatible encodings).</p> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">gettext.NullTranslations</span></tt></a></dt> <dd>For information about what methods are available and what they do.</dd> </dl> </div> <p class="versionchanged"> <span class="versionmodified">Changed in version kitchen-1.1.0: </span>; API kitchen.i18n 2.1.0 * Although we had adapted <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt>, <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt>, <tt class="xref py py-meth docutils literal"><span class="pre">lgettext()</span></tt>, and <tt class="xref py py-meth docutils literal"><span class="pre">lngettext()</span></tt> to always return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>, we hadn’t forced those byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to always be in a specified charset. We now make sure that <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt> return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> encoded using <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt> if set, otherwise <tt class="xref py py-attr docutils literal"><span class="pre">charset</span></tt> and if neither of those, <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a>. With <tt class="xref py py-meth docutils literal"><span class="pre">lgettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">lngettext()</span></tt> <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt> if set, otherwise <a class="reference external" href="http://docs.python.org/library/locale.html#locale.getpreferredencoding" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">locale.getpreferredencoding()</span></tt></a>. * Make setting <a class="reference internal" href="#kitchen.i18n.DummyTranslations.input_charset" title="kitchen.i18n.DummyTranslations.input_charset"><tt class="xref py py-attr docutils literal"><span class="pre">input_charset</span></tt></a> and <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt> also set those attributes on any fallback translation objects.</p> <dl class="method"> <dt id="kitchen.i18n.DummyTranslations.set_output_charset"> <tt class="descname">set_output_charset</tt><big>(</big><em>charset</em><big>)</big><a class="headerlink" href="#kitchen.i18n.DummyTranslations.set_output_charset" title="Permalink to this definition">¶</a></dt> <dd><p>Set the output charset</p> <p>This serves two purposes. The normal <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations.set_output_charset" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">gettext.NullTranslations.set_output_charset()</span></tt></a> does not set the output on fallback objects. On python-2.3, <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.NullTranslations" title="(in Python v2.7)"><tt class="xref py py-class docutils literal"><span class="pre">gettext.NullTranslations</span></tt></a> objects don’t contain this method.</p> </dd></dl> </dd></dl> <dl class="class"> <dt id="kitchen.i18n.NewGNUTranslations"> <em class="property">class </em><tt class="descclassname">kitchen.i18n.</tt><tt class="descname">NewGNUTranslations</tt><big>(</big><em>fp=None</em><big>)</big><a class="headerlink" href="#kitchen.i18n.NewGNUTranslations" title="Permalink to this definition">¶</a></dt> <dd><p>Safer version of <tt class="xref py py-class docutils literal"><span class="pre">gettext.GNUTranslations</span></tt></p> <p><tt class="xref py py-class docutils literal"><span class="pre">gettext.GNUTranslations</span></tt> suffers from two problems that this class fixes.</p> <ol class="arabic simple"> <li><tt class="xref py py-class docutils literal"><span class="pre">gettext.GNUTranslations</span></tt> can throw a <a class="reference external" href="http://docs.python.org/library/exceptions.html#exceptions.UnicodeError" title="(in Python v2.7)"><tt class="xref py py-exc docutils literal"><span class="pre">UnicodeError</span></tt></a> in <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.GNUTranslations.ugettext" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">gettext.GNUTranslations.ugettext()</span></tt></a> if the message being translated has non-<a class="reference internal" href="glossary.html#term-ascii"><em class="xref std std-term">ASCII</em></a> characters and there is no translation for it.</li> <li><tt class="xref py py-class docutils literal"><span class="pre">gettext.GNUTranslations</span></tt> can return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> from <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.GNUTranslations.ugettext" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">gettext.GNUTranslations.ugettext()</span></tt></a> and <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings from the other <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext.GNUTranslations.gettext" title="(in Python v2.7)"><tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt></a> methods if the message being translated is the wrong type</li> </ol> <p>When byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> are returned, the strings will be encoded according to this algorithm:</p> <ol class="arabic simple"> <li>If a fallback has been added, the fallback will be called first. You’ll need to consult the fallback to see whether it performs any encoding changes.</li> <li>If a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> was given, the same byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> will be returned.</li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and <tt class="xref py py-meth docutils literal"><span class="pre">set_output_charset()</span></tt> has been called then we encode the string using the <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt></li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and this is <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt> and a charset was detected when parsing the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a>, output in that charset.</li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and this is <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt> we encode it using <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a>.</li> <li>If a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string was given and this is <tt class="xref py py-meth docutils literal"><span class="pre">lgettext()</span></tt> or <tt class="xref py py-meth docutils literal"><span class="pre">lngettext()</span></tt> we encode using the value of <a class="reference external" href="http://docs.python.org/library/locale.html#locale.getpreferredencoding" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">locale.getpreferredencoding()</span></tt></a></li> </ol> <p>For <tt class="xref py py-meth docutils literal"><span class="pre">ugettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ungettext()</span></tt>, we go through the same set of steps with the following differences:</p> <ul class="simple"> <li>We transform byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> into <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> strings for these methods.</li> <li>The encoding used to decode the byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> is taken from <a class="reference internal" href="#kitchen.i18n.NewGNUTranslations.input_charset" title="kitchen.i18n.NewGNUTranslations.input_charset"><tt class="xref py py-attr docutils literal"><span class="pre">input_charset</span></tt></a> if it’s set, otherwise we decode using <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a></li> </ul> <dl class="attribute"> <dt id="kitchen.i18n.NewGNUTranslations.input_charset"> <tt class="descname">input_charset</tt><a class="headerlink" href="#kitchen.i18n.NewGNUTranslations.input_charset" title="Permalink to this definition">¶</a></dt> <dd><p>an extension to the <a class="reference external" href="http://docs.python.org/library">python standard library</a> <a class="reference external" href="http://docs.python.org/library/gettext.html#gettext" title="(in Python v2.7)"><tt class="xref py py-mod docutils literal"><span class="pre">gettext</span></tt></a> that specifies what charset a message is encoded in when decoding a message to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>. This is used for two purposes:</p> </dd></dl> <ol class="arabic simple"> <li>If the message string is a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>, this is used to decode the string to a <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string before looking it up in the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a>.</li> <li>In <tt class="xref py py-meth docutils literal"><span class="pre">ugettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ungettext()</span></tt> methods, if a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> is given as the message and is untranslated his is used as the encoding when decoding to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt>. This is different from the <tt class="xref py py-attr docutils literal"><span class="pre">_charset</span></tt> parameter that may be set when a <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a> is loaded because <a class="reference internal" href="#kitchen.i18n.NewGNUTranslations.input_charset" title="kitchen.i18n.NewGNUTranslations.input_charset"><tt class="xref py py-attr docutils literal"><span class="pre">input_charset</span></tt></a> is used to describe an encoding used in a python source file while <tt class="xref py py-attr docutils literal"><span class="pre">_charset</span></tt> describes the encoding used in the <a class="reference internal" href="glossary.html#term-message-catalog"><em class="xref std std-term">message catalog</em></a> file.</li> </ol> <p>Any characters that aren’t able to be transformed from a byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to <tt class="xref py py-class docutils literal"><span class="pre">unicode</span></tt> string or vice versa will be replaced with a replacement character (ie: <tt class="docutils literal"><span class="pre">u'�'</span></tt> in unicode based encodings, <tt class="docutils literal"><span class="pre">'?'</span></tt> in other <a class="reference internal" href="glossary.html#term-ascii"><em class="xref std std-term">ASCII</em></a> compatible encodings).</p> <div class="admonition-see-also admonition seealso"> <p class="first admonition-title">See also</p> <dl class="last docutils"> <dt><tt class="xref py py-class docutils literal"><span class="pre">gettext.GNUTranslations.gettext</span></tt></dt> <dd>For information about what methods this class has and what they do</dd> </dl> </div> <p class="versionchanged"> <span class="versionmodified">Changed in version kitchen-1.1.0: </span>; API kitchen.i18n 2.1.0 Although we had adapted <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt>, <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt>, <tt class="xref py py-meth docutils literal"><span class="pre">lgettext()</span></tt>, and <tt class="xref py py-meth docutils literal"><span class="pre">lngettext()</span></tt> to always return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt>, we hadn’t forced those byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> to always be in a specified charset. We now make sure that <tt class="xref py py-meth docutils literal"><span class="pre">gettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">ngettext()</span></tt> return byte <tt class="xref py py-class docutils literal"><span class="pre">str</span></tt> encoded using <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt> if set, otherwise <tt class="xref py py-attr docutils literal"><span class="pre">charset</span></tt> and if neither of those, <a class="reference internal" href="glossary.html#term-utf-8"><em class="xref std std-term">UTF-8</em></a>. With <tt class="xref py py-meth docutils literal"><span class="pre">lgettext()</span></tt> and <tt class="xref py py-meth docutils literal"><span class="pre">lngettext()</span></tt> <tt class="xref py py-attr docutils literal"><span class="pre">output_charset</span></tt> if set, otherwise <a class="reference external" href="http://docs.python.org/library/locale.html#locale.getpreferredencoding" title="(in Python v2.7)"><tt class="xref py py-func docutils literal"><span class="pre">locale.getpreferredencoding()</span></tt></a>.</p> </dd></dl> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference internal" href="#">Kitchen.i18n Module</a><ul> <li><a class="reference internal" href="#functions">Functions</a></li> <li><a class="reference internal" href="#translation-objects">Translation Objects</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="api-overview.html" title="previous chapter">Kitchen API</a></p> <h4>Next topic</h4> <p class="topless"><a href="api-text.html" title="next chapter">Kitchen.text: unicode and utf8 and xml oh my!</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/api-i18n.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="api-text.html" title="Kitchen.text: unicode and utf8 and xml oh my!" >next</a> |</li> <li class="right" > <a href="api-overview.html" title="Kitchen API" >previous</a> |</li> <li><a href="index.html">kitchen 1.1.1 documentation</a> »</li> <li><a href="api-overview.html" >Kitchen API</a> »</li> </ul> </div> <div class="footer"> © Copyright 2011 Red Hat, Inc. and others. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3. </div> </body> </html>