<!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>Using internationalization in your own projects — Django v1.3.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.3.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="top" title="Django v1.3.1 documentation" href="../index.html" />
<link rel="up" title="“How-to” guides" href="index.html" />
<link rel="next" title="Running Django on Jython" href="jython.html" />
<link rel="prev" title="Providing initial data for models" href="initial-data.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django v1.3.1 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="initial-data.html" title="Providing initial data for models">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="jython.html" title="Running Django on Jython">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="howto-i18n">
<div class="section" id="s-using-internationalization-in-your-own-projects">
<span id="s-using-translations-in-your-own-projects"></span><span id="using-internationalization-in-your-own-projects"></span><span id="using-translations-in-your-own-projects"></span><h1>Using internationalization in your own projects<a class="headerlink" href="#using-internationalization-in-your-own-projects" title="Permalink to this headline">¶</a></h1>
<p>At runtime, Django builds an in-memory unified catalog of literals-translations.
To achieve this it looks for translations by following this algorithm regarding
the order in which it examines the different file paths to load the compiled
<a class="reference internal" href="../topics/i18n/index.html#term-message-file"><em class="xref std std-term">message files</em></a> (<tt class="docutils literal"><span class="pre">.mo</span></tt>) and the precedence of multiple
translations for the same literal:</p>
<ol class="arabic simple">
<li>The directories listed in <a class="reference internal" href="../ref/settings.html#std:setting-LOCALE_PATHS"><tt class="xref std std-setting docutils literal"><span class="pre">LOCALE_PATHS</span></tt></a> have the highest
precedence, with the ones appearing first having higher precedence than
the ones appearing later.</li>
<li>Then, it looks for and uses if it exists a <tt class="docutils literal"><span class="pre">locale</span></tt> directory in each
of the installed apps listed in <a class="reference internal" href="../ref/settings.html#std:setting-INSTALLED_APPS"><tt class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></tt></a>. The ones
appearing first have higher precedence than the ones appearing later.</li>
<li>Then, it looks for a <tt class="docutils literal"><span class="pre">locale</span></tt> directory in the project directory, or
more accurately, in the directory containing your settings file.</li>
<li>Finally, the Django-provided base translation in <tt class="docutils literal"><span class="pre">django/conf/locale</span></tt>
is used as a fallback.</li>
</ol>
<div class="deprecated">
<span class="title">Deprecated in Django 1.3:</span> Lookup in the <tt class="docutils literal"><span class="pre">locale</span></tt> subdirectory of the directory containing your
settings file (item 3 above) is deprecated since the 1.3 release and will be
removed in Django 1.5. You can use the <a class="reference internal" href="../ref/settings.html#std:setting-LOCALE_PATHS"><tt class="xref std std-setting docutils literal"><span class="pre">LOCALE_PATHS</span></tt></a> setting
instead, by listing the absolute filesystem path of such <tt class="docutils literal"><span class="pre">locale</span></tt>
directory in the setting value.</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The translations for literals included in JavaScript assets are looked up
following a similar but not identical algorithm. See the
<a class="reference internal" href="../topics/i18n/internationalization.html#javascript-catalog-view"><em>javascript_catalog view documentation</em></a> for
more details.</p>
</div>
<p>In all cases the name of the directory containing the translation is expected to
be named using <a class="reference internal" href="../topics/i18n/index.html#term-locale-name"><em class="xref std std-term">locale name</em></a> notation. E.g. <tt class="docutils literal"><span class="pre">de</span></tt>, <tt class="docutils literal"><span class="pre">pt_BR</span></tt>, <tt class="docutils literal"><span class="pre">es_AR</span></tt>,
etc.</p>
<p>This way, you can write applications that include their own translations, and
you can override base translations in your project path. Or, you can just build
a big project out of several apps and put all translations into one big common
message file specific to the project you are composing. The choice is yours.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">If you’re using manually configured settings, as described in
<a class="reference internal" href="../topics/settings.html#settings-without-django-settings-module"><em>Using settings without setting DJANGO_SETTINGS_MODULE</em></a>, the <tt class="docutils literal"><span class="pre">locale</span></tt> directory in
the project directory will not be examined, since Django loses the ability
to work out the location of the project directory. (Django normally uses the
location of the settings file to determine this, and a settings file doesn’t
exist if you’re manually configuring your settings.)</p>
</div>
<p>All message file repositories are structured the same way. They are:</p>
<ul class="simple">
<li>All paths listed in <a class="reference internal" href="../ref/settings.html#std:setting-LOCALE_PATHS"><tt class="xref std std-setting docutils literal"><span class="pre">LOCALE_PATHS</span></tt></a> in your settings file are
searched for <tt class="docutils literal"><span class="pre"><language>/LC_MESSAGES/django.(po|mo)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">$PROJECTPATH/locale/<language>/LC_MESSAGES/django.(po|mo)</span></tt> –
deprecated, see above.</li>
<li><tt class="docutils literal"><span class="pre">$APPPATH/locale/<language>/LC_MESSAGES/django.(po|mo)</span></tt></li>
<li><tt class="docutils literal"><span class="pre">$PYTHONPATH/django/conf/locale/<language>/LC_MESSAGES/django.(po|mo)</span></tt></li>
</ul>
<p>To create message files, you use the <a class="reference internal" href="../ref/django-admin.html#django-admin-makemessages"><tt class="xref std std-djadmin docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt></a>
tool. You only need to be in the same directory where the <tt class="docutils literal"><span class="pre">locale/</span></tt> directory
is located. And you use <a class="reference internal" href="../ref/django-admin.html#django-admin-compilemessages"><tt class="xref std std-djadmin docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span></tt></a>
to produce the binary <tt class="docutils literal"><span class="pre">.mo</span></tt> files that are used by <tt class="docutils literal"><span class="pre">gettext</span></tt>. Read the
<a class="reference internal" href="../topics/i18n/localization.html"><em>Localization</em></a> document for more details.</p>
<p>You can also run <tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">compilemessages</span> <span class="pre">--settings=path.to.settings</span></tt>
to make the compiler process all the directories in your <a class="reference internal" href="../ref/settings.html#std:setting-LOCALE_PATHS"><tt class="xref std std-setting docutils literal"><span class="pre">LOCALE_PATHS</span></tt></a>
setting.</p>
<p>Finally, you should give some thought to the structure of your translation
files. If your applications need to be delivered to other users and will
be used in other projects, you might want to use app-specific translations.
But using app-specific translations and project-specific translations could
produce weird problems with <tt class="docutils literal"><span class="pre">makemessages</span></tt>: It will traverse all directories
below the current path and so might put message IDs into a unified, common
message file for the current project that are already in application message
files.</p>
<p>The easiest way out is to store applications that are not part of the project
(and so carry their own translations) outside the project tree. That way,
<tt class="docutils literal"><span class="pre">django-admin.py</span> <span class="pre">makemessages</span></tt>, when ran on a project level will only extract
strings that are connected to your explicit project and not strings that are
distributed independently.</p>
<div class="section" id="s-using-translations-outside-views-and-templates">
<span id="using-translations-outside-views-and-templates"></span><h2>Using translations outside views and templates<a class="headerlink" href="#using-translations-outside-views-and-templates" title="Permalink to this headline">¶</a></h2>
<p>While Django provides a rich set of i18n tools for use in views and templates,
it does not restrict the usage to Django-specific code. The Django translation
mechanisms can be used to translate arbitrary texts to any language that is
supported by Django (as long as an appropriate translation catalog exists, of
course). You can load a translation catalog, activate it and translate text to
language of your choice, but remember to switch back to original language, as
activating a translation catalog is done on per-thread basis and such change
will affect code running in the same thread.</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.utils</span> <span class="kn">import</span> <span class="n">translation</span>
<span class="k">def</span> <span class="nf">welcome_translated</span><span class="p">(</span><span class="n">language</span><span class="p">):</span>
<span class="n">cur_language</span> <span class="o">=</span> <span class="n">translation</span><span class="o">.</span><span class="n">get_language</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">translation</span><span class="o">.</span><span class="n">activate</span><span class="p">(</span><span class="n">language</span><span class="p">)</span>
<span class="n">text</span> <span class="o">=</span> <span class="n">translation</span><span class="o">.</span><span class="n">ugettext</span><span class="p">(</span><span class="s">'welcome'</span><span class="p">)</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">translation</span><span class="o">.</span><span class="n">activate</span><span class="p">(</span><span class="n">cur_language</span><span class="p">)</span>
<span class="k">return</span> <span class="n">text</span>
</pre></div>
</div>
<p>Calling this function with the value 'de' will give you <tt class="docutils literal"><span class="pre">"Willkommen"</span></tt>,
regardless of <a class="reference internal" href="../ref/settings.html#std:setting-LANGUAGE_CODE"><tt class="xref std std-setting docutils literal"><span class="pre">LANGUAGE_CODE</span></tt></a> and language set by middleware.</p>
<p>Functions of particular interest are <tt class="docutils literal"><span class="pre">django.utils.translation.get_language()</span></tt>
which returns the language used in the current thread,
<tt class="docutils literal"><span class="pre">django.utils.translation.activate()</span></tt> which activates a translation catalog
for the current thread, and <tt class="docutils literal"><span class="pre">django.utils.translation.check_for_language()</span></tt>
which checks if the given language is supported by Django.</p>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using internationalization in your own projects</a><ul>
<li><a class="reference internal" href="#using-translations-outside-views-and-templates">Using translations outside views and templates</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="initial-data.html">Providing initial data for models</a></li>
<li>Next: <a href="jython.html">Running Django on Jython</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django v1.3.1 documentation</a>
<ul><li><a href="index.html">“How-to” guides</a>
<ul><li>Using internationalization in your own projects</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/howto/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" size="18" />
<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>
<h3>Last update:</h3>
<p class="topless">Sep 10, 2011</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="initial-data.html" title="Providing initial data for models">previous</a>
|
<a href="index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="jython.html" title="Running Django on Jython">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
