/usr/share/doc/python-django-modeltranslation/html/usage.html is in python-django-modeltranslation-doc 0.12.2-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 | <!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>Accessing Translated and Translation Fields — django-modeltranslation 0.12.2 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '0.12.2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="ModelForms" href="forms.html" />
<link rel="prev" title="Registering Models for Translation" href="registration.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<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="forms.html" title="ModelForms"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="registration.html" title="Registering Models for Translation"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">django-modeltranslation 0.12.2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="accessing-translated-and-translation-fields">
<span id="usage"></span><h1>Accessing Translated and Translation Fields<a class="headerlink" href="#accessing-translated-and-translation-fields" title="Permalink to this headline">¶</a></h1>
<p>Modeltranslation changes the behaviour of the translated fields. To
explain this consider the news example from the <a class="reference internal" href="registration.html#registration"><span class="std std-ref">Registering Models for Translation</span></a> chapter
again. The original <code class="docutils literal"><span class="pre">News</span></code> model looked like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">News</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="n">title</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">)</span>
<span class="n">text</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">()</span>
</pre></div>
</div>
<p>Now that it is registered with modeltranslation the model looks
like this - note the additional fields automatically added by the app:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">News</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="n">title</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">)</span> <span class="c1"># original/translated field</span>
<span class="n">title_de</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">null</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">blank</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">)</span> <span class="c1"># default translation field</span>
<span class="n">title_en</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">null</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">blank</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">max_length</span><span class="o">=</span><span class="mi">255</span><span class="p">)</span> <span class="c1"># translation field</span>
<span class="n">text</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">()</span> <span class="c1"># original/translated field</span>
<span class="n">text_de</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">(</span><span class="n">null</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">blank</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="c1"># default translation field</span>
<span class="n">text_en</span> <span class="o">=</span> <span class="n">models</span><span class="o">.</span><span class="n">TextField</span><span class="p">(</span><span class="n">null</span><span class="o">=</span><span class="kc">True</span><span class="p">,</span> <span class="n">blank</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span> <span class="c1"># translation field</span>
</pre></div>
</div>
<p>The example above assumes that the default language is <code class="docutils literal"><span class="pre">de</span></code>, therefore the
<code class="docutils literal"><span class="pre">title_de</span></code> and <code class="docutils literal"><span class="pre">text_de</span></code> fields are marked as the <em>default translation
fields</em>. If the default language is <code class="docutils literal"><span class="pre">en</span></code>, the <code class="docutils literal"><span class="pre">title_en</span></code> and <code class="docutils literal"><span class="pre">text_en</span></code>
fields would be the <em>default translation fields</em>.</p>
<div class="section" id="rules-for-translated-field-access">
<span id="rules"></span><h2>Rules for Translated Field Access<a class="headerlink" href="#rules-for-translated-field-access" title="Permalink to this headline">¶</a></h2>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.5.</span></p>
</div>
<p>So now when it comes to setting and getting the value of the original and the
translation fields the following rules apply:</p>
<p><strong>Rule 1</strong></p>
<blockquote>
<div>Reading the value from the original field returns the value translated to
the current language.</div></blockquote>
<p><strong>Rule 2</strong></p>
<blockquote>
<div>Assigning a value to the original field updates the value in the associated
current language translation field.</div></blockquote>
<p><strong>Rule 3</strong></p>
<blockquote>
<div><p>If both fields - the original and the current language translation field -
are updated at the same time, the current language translation field wins.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This can only happen in the model’s constructor or
<code class="docutils literal"><span class="pre">objects.create</span></code>. There is no other situation which can be considered
<em>changing several fields at the same time</em>.</p>
</div>
</div></blockquote>
</div>
<div class="section" id="examples-for-translated-field-access">
<h2>Examples for Translated Field Access<a class="headerlink" href="#examples-for-translated-field-access" title="Permalink to this headline">¶</a></h2>
<p>Because the whole point of using the modeltranslation app is translating
dynamic content, the fields marked for translation are somehow special when it
comes to accessing them. The value returned by a translated field is depending
on the current language setting. “Language setting” is referring to the Django
<a class="reference external" href="https://docs.djangoproject.com/en/dev/topics/i18n/translation/#set-language-redirect-view">set_language</a> view and the corresponding <code class="docutils literal"><span class="pre">get_lang</span></code> function.</p>
<p>Assuming the current language is <code class="docutils literal"><span class="pre">de</span></code> in the news example from above, the
translated <code class="docutils literal"><span class="pre">title</span></code> field will return the value from the <code class="docutils literal"><span class="pre">title_de</span></code> field:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Assuming the current language is "de"</span>
<span class="n">n</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">n</span><span class="o">.</span><span class="n">title</span> <span class="c1"># returns german translation</span>
<span class="c1"># Assuming the current language is "en"</span>
<span class="n">t</span> <span class="o">=</span> <span class="n">n</span><span class="o">.</span><span class="n">title</span> <span class="c1"># returns english translation</span>
</pre></div>
</div>
<p>This feature is implemented using Python descriptors making it happen without
the need to touch the original model classes in any way. The descriptor uses
the <code class="docutils literal"><span class="pre">django.utils.i18n.get_language</span></code> function to determine the current
language.</p>
<div class="admonition-todo admonition" id="index-0">
<p class="first admonition-title">Todo</p>
<p class="last">Add more examples.</p>
</div>
</div>
<div class="section" id="multilingual-manager">
<span id="id1"></span><h2>Multilingual Manager<a class="headerlink" href="#multilingual-manager" title="Permalink to this headline">¶</a></h2>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
<p>Every model registered for translation is patched so that all its managers become subclasses
of <code class="docutils literal"><span class="pre">MultilingualManager</span></code> (of course, if a custom manager was defined on the model, its
functions will be retained). <code class="docutils literal"><span class="pre">MultilingualManager</span></code> simplifies language-aware queries,
especially on third-party apps, by rewriting query field names.</p>
<p>Every model’s manager is patched, not only <code class="docutils literal"><span class="pre">objects</span></code> (even managers inherited from abstract base
classes).</p>
<p>For example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Assuming the current language is "de",</span>
<span class="c1"># these queries returns the same objects</span>
<span class="n">news1</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">title__contains</span><span class="o">=</span><span class="s1">'enigma'</span><span class="p">)</span>
<span class="n">news2</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">title_de__contains</span><span class="o">=</span><span class="s1">'enigma'</span><span class="p">)</span>
<span class="k">assert</span> <span class="n">news1</span> <span class="o">==</span> <span class="n">news2</span>
</pre></div>
</div>
<p>It works as follow: if the translation field name is used (<code class="docutils literal"><span class="pre">title</span></code>), it is changed into the
current language field name (<code class="docutils literal"><span class="pre">title_de</span></code> or <code class="docutils literal"><span class="pre">title_en</span></code>, depending on the current active
language).
Any language-suffixed names are left untouched (so <code class="docutils literal"><span class="pre">title_en</span></code> wouldn’t change,
no matter what the current language is).</p>
<p>Rewriting of field names works with operators (like <code class="docutils literal"><span class="pre">__in</span></code>, <code class="docutils literal"><span class="pre">__ge</span></code>) as well as with
relationship spanning. Moreover, it is also handled on <code class="docutils literal"><span class="pre">Q</span></code> and <code class="docutils literal"><span class="pre">F</span></code> expressions.</p>
<p>These manager methods perform rewriting:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">filter()</span></code>, <code class="docutils literal"><span class="pre">exclude()</span></code>, <code class="docutils literal"><span class="pre">get()</span></code></li>
<li><code class="docutils literal"><span class="pre">order_by()</span></code></li>
<li><code class="docutils literal"><span class="pre">update()</span></code></li>
<li><code class="docutils literal"><span class="pre">only()</span></code>, <code class="docutils literal"><span class="pre">defer()</span></code></li>
<li><code class="docutils literal"><span class="pre">values()</span></code>, <code class="docutils literal"><span class="pre">values_list()</span></code>, with <a class="reference internal" href="#fallback"><span class="std std-ref">fallback</span></a> mechanism</li>
<li><code class="docutils literal"><span class="pre">dates()</span></code></li>
<li><code class="docutils literal"><span class="pre">select_related()</span></code></li>
<li><code class="docutils literal"><span class="pre">create()</span></code>, with optional <a class="reference internal" href="#auto-population">auto-population</a> feature</li>
</ul>
<p>In order not to introduce differences between <code class="docutils literal"><span class="pre">X.objects.create(...)</span></code> and <code class="docutils literal"><span class="pre">X(...)</span></code>, model
constructor is also patched and performs rewriting of field names prior to regular initialization.</p>
<p>If one wants to turn rewriting of field names off, this can be easily achieved with
<code class="docutils literal"><span class="pre">rewrite(mode)</span></code> method. <code class="docutils literal"><span class="pre">mode</span></code> is a boolean specifying whether rewriting should be applied.
It can be changed several times inside a query. So <code class="docutils literal"><span class="pre">X.objects.rewrite(False)</span></code> turns rewriting off.</p>
<p><code class="docutils literal"><span class="pre">MultilingualManager</span></code> offers one additional method: <code class="docutils literal"><span class="pre">raw_values</span></code>. It returns actual values from
the database, without field names rewriting. Useful for checking translated field database value.</p>
<div class="section" id="auto-population">
<h3>Auto-population<a class="headerlink" href="#auto-population" title="Permalink to this headline">¶</a></h3>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.6.</span></p>
</div>
<p>There is special manager method <code class="docutils literal"><span class="pre">populate(mode)</span></code> which can trigger <code class="docutils literal"><span class="pre">create()</span></code> or
<code class="docutils literal"><span class="pre">get_or_create()</span></code> to populate all translation (language) fields with values from translated
(original) ones. It can be very convenient when working with many languages. So:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">populate</span><span class="p">(</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span>
</pre></div>
</div>
<p>is equivalent of:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">title_en</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">,</span> <span class="n">title_de</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span> <span class="c1">## title_?? for every language</span>
</pre></div>
</div>
<p>Moreover, some fields can be explicitly assigned different values:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">x</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">populate</span><span class="p">(</span><span class="kc">True</span><span class="p">)</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s1">'-- no translation yet --'</span><span class="p">,</span> <span class="n">title_de</span><span class="o">=</span><span class="s1">'enigma'</span><span class="p">)</span>
</pre></div>
</div>
<p>It will result in <code class="docutils literal"><span class="pre">title_de</span> <span class="pre">==</span> <span class="pre">'enigma'</span></code> and other <code class="docutils literal"><span class="pre">title_??</span> <span class="pre">==</span> <span class="pre">'--</span> <span class="pre">no</span> <span class="pre">translation</span> <span class="pre">yet</span> <span class="pre">--'</span></code>.</p>
<p>There is another way of altering the current population status, an <code class="docutils literal"><span class="pre">auto_populate</span></code> context
manager:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">modeltranslation.utils</span> <span class="k">import</span> <span class="n">auto_populate</span>
<span class="k">with</span> <span class="n">auto_populate</span><span class="p">(</span><span class="kc">True</span><span class="p">):</span>
<span class="n">x</span> <span class="o">=</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span>
</pre></div>
</div>
<p>Auto-population takes place also in model constructor, what is extremely useful when loading
non-translated fixtures. Just remember to use the context manager:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">auto_populate</span><span class="p">():</span> <span class="c1"># True can be ommited</span>
<span class="n">call_command</span><span class="p">(</span><span class="s1">'loaddata'</span><span class="p">,</span> <span class="s1">'fixture.json'</span><span class="p">)</span> <span class="c1"># Some fixture loading</span>
<span class="n">z</span> <span class="o">=</span> <span class="n">News</span><span class="p">(</span><span class="n">title</span><span class="o">=</span><span class="s1">'bar'</span><span class="p">)</span>
<span class="nb">print</span> <span class="n">z</span><span class="o">.</span><span class="n">title_en</span><span class="p">,</span> <span class="n">z</span><span class="o">.</span><span class="n">title_de</span> <span class="c1"># prints 'bar bar'</span>
</pre></div>
</div>
<p>There is a more convenient way than calling <code class="docutils literal"><span class="pre">populate</span></code> manager method or entering
<code class="docutils literal"><span class="pre">auto_populate</span></code> manager context all the time:
<a class="reference internal" href="installation.html#settings-modeltranslation-auto-populate"><span class="std std-ref">MODELTRANSLATION_AUTO_POPULATE</span></a> setting.
It controls the default population behaviour.</p>
<div class="section" id="auto-population-modes">
<span id="id2"></span><h4>Auto-population modes<a class="headerlink" href="#auto-population-modes" title="Permalink to this headline">¶</a></h4>
<p>There are four different population modes:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">False</span></code></dt>
<dd><p class="first">[set by default]</p>
<p class="last">Auto-population turned off</p>
</dd>
<dt><code class="docutils literal"><span class="pre">True</span></code> or <code class="docutils literal"><span class="pre">'all'</span></code></dt>
<dd><p class="first">[default argument to population altering methods]</p>
<p class="last">Auto-population turned on, copying translated field value to all other languages
(unless a translation field value is provided)</p>
</dd>
<dt><code class="docutils literal"><span class="pre">'default'</span></code></dt>
<dd>Auto-population turned on, copying translated field value to default language field
(unless its value is provided)</dd>
<dt><code class="docutils literal"><span class="pre">'required'</span></code></dt>
<dd>Acts like <code class="docutils literal"><span class="pre">'default'</span></code>, but copy value only if the original field is non-nullable</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="falling-back">
<span id="fallback"></span><h2>Falling back<a class="headerlink" href="#falling-back" title="Permalink to this headline">¶</a></h2>
<p>Modeltranslation provides a mechanism to control behaviour of data access in case of empty
translation values. This mechanism affects field access, as well as <code class="docutils literal"><span class="pre">values()</span></code>
and <code class="docutils literal"><span class="pre">values_list()</span></code> manager methods.</p>
<p>Consider the <code class="docutils literal"><span class="pre">News</span></code> example: a creator of some news hasn’t specified its German title and
content, but only English ones. Then if a German visitor is viewing the site, we would rather show
him English title/content of the news than display empty strings. This is called <em>fallback</em>.</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">news</span><span class="o">.</span><span class="n">title_en</span> <span class="o">=</span> <span class="s1">'English title'</span>
<span class="n">news</span><span class="o">.</span><span class="n">title_de</span> <span class="o">=</span> <span class="s1">''</span>
<span class="nb">print</span> <span class="n">news</span><span class="o">.</span><span class="n">title</span>
<span class="c1"># If current active language is German, it should display the title_de field value ('').</span>
<span class="c1"># But if fallback is enabled, it would display 'English title' instead.</span>
<span class="c1"># Similarly for manager</span>
<span class="n">news</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="nb">print</span> <span class="n">News</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">filter</span><span class="p">(</span><span class="n">pk</span><span class="o">=</span><span class="n">news</span><span class="o">.</span><span class="n">pk</span><span class="p">)</span><span class="o">.</span><span class="n">values_list</span><span class="p">(</span><span class="s1">'title'</span><span class="p">,</span> <span class="n">flat</span><span class="o">=</span><span class="kc">True</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="c1"># As above: if current active language is German and fallback to English is enabled,</span>
<span class="c1"># it would display 'English title'.</span>
</pre></div>
</div>
<p>There are several ways of controlling fallback, described below.</p>
<div class="section" id="fallback-languages">
<span id="fallback-lang"></span><h3>Fallback languages<a class="headerlink" href="#fallback-languages" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.5.</span></p>
</div>
<p><a class="reference internal" href="installation.html#settings-modeltranslation-fallback-languages"><span class="std std-ref">MODELTRANSLATION_FALLBACK_LANGUAGES</span></a> setting allows to set the order of <em>fallback
languages</em>. By default that’s the <code class="docutils literal"><span class="pre">DEFAULT_LANGUAGE</span></code>.</p>
<p>For example, setting</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">MODELTRANSLATION_FALLBACK_LANGUAGES</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'en'</span><span class="p">,</span> <span class="s1">'de'</span><span class="p">,</span> <span class="s1">'fr'</span><span class="p">)</span>
</pre></div>
</div>
<p>means: if current active language field value is unset, try English value. If it is also unset,
try German, and so on - until some language yields a non-empty value of the field.</p>
<p>There is also an option to define a fallback by language, using dict syntax:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">MODELTRANSLATION_FALLBACK_LANGUAGES</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'default'</span><span class="p">:</span> <span class="p">(</span><span class="s1">'en'</span><span class="p">,</span> <span class="s1">'de'</span><span class="p">,</span> <span class="s1">'fr'</span><span class="p">),</span>
<span class="s1">'fr'</span><span class="p">:</span> <span class="p">(</span><span class="s1">'de'</span><span class="p">,),</span>
<span class="s1">'uk'</span><span class="p">:</span> <span class="p">(</span><span class="s1">'ru'</span><span class="p">,)</span>
<span class="p">}</span>
</pre></div>
</div>
<p>The <code class="docutils literal"><span class="pre">default</span></code> key is required and its value denote languages which are always tried at the end.
With such a setting:</p>
<ul class="simple">
<li>for <cite>uk</cite> the order of fallback languages is: <code class="docutils literal"><span class="pre">('ru',</span> <span class="pre">'en',</span> <span class="pre">'de',</span> <span class="pre">'fr')</span></code></li>
<li>for <cite>fr</cite> the order of fallback languages is: <code class="docutils literal"><span class="pre">('de',</span> <span class="pre">'en')</span></code> - Note, that <cite>fr</cite> obviously is not
a fallback, since its active language and <cite>de</cite> would be tried before <cite>en</cite></li>
<li>for <cite>en</cite> and <cite>de</cite> the fallback order is <code class="docutils literal"><span class="pre">('de',</span> <span class="pre">'fr')</span></code> and <code class="docutils literal"><span class="pre">('en',</span> <span class="pre">'fr')</span></code>, respectively</li>
<li>for any other language the order of fallback languages is just <code class="docutils literal"><span class="pre">('en',</span> <span class="pre">'de',</span> <span class="pre">'fr')</span></code></li>
</ul>
<p>What is more, fallback languages order can be overridden per model, using <code class="docutils literal"><span class="pre">TranslationOptions</span></code>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">NewsTranslationOptions</span><span class="p">(</span><span class="n">TranslationOptions</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'title'</span><span class="p">,</span> <span class="s1">'text'</span><span class="p">,)</span>
<span class="n">fallback_languages</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'default'</span><span class="p">:</span> <span class="p">(</span><span class="s1">'fa'</span><span class="p">,</span> <span class="s1">'km'</span><span class="p">)}</span> <span class="c1"># use Persian and Khmer as fallback for News</span>
</pre></div>
</div>
<p>Dict syntax is only allowed there.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.6.</span></p>
</div>
<p>Even more, all fallbacks may be switched on or off for just some exceptional block of code using:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">modeltranslation.utils</span> <span class="k">import</span> <span class="n">fallbacks</span>
<span class="k">with</span> <span class="n">fallbacks</span><span class="p">(</span><span class="kc">False</span><span class="p">):</span>
<span class="c1"># Work with values for the active language only</span>
</pre></div>
</div>
</div>
<div class="section" id="fallback-values">
<span id="fallback-val"></span><h3>Fallback values<a class="headerlink" href="#fallback-values" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.4.</span></p>
</div>
<p>But what if current language and all fallback languages yield no field value? Then modeltranslation
will use the field’s <em>fallback value</em>, if one was defined.</p>
<p>Fallback values are defined in <code class="docutils literal"><span class="pre">TranslationOptions</span></code>, for example:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">NewsTranslationOptions</span><span class="p">(</span><span class="n">TranslationOptions</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'title'</span><span class="p">,</span> <span class="s1">'text'</span><span class="p">,)</span>
<span class="n">fallback_values</span> <span class="o">=</span> <span class="n">_</span><span class="p">(</span><span class="s1">'-- sorry, no translation provided --'</span><span class="p">)</span>
</pre></div>
</div>
<p>In this case, if title is missing in active language and any of fallback languages, news title
will be <code class="docutils literal"><span class="pre">'--</span> <span class="pre">sorry,</span> <span class="pre">no</span> <span class="pre">translation</span> <span class="pre">provided</span> <span class="pre">--'</span></code> (maybe translated, since gettext is used).
Empty text will be handled in same way.</p>
<p>Fallback values can be also customized per model field:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">NewsTranslationOptions</span><span class="p">(</span><span class="n">TranslationOptions</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'title'</span><span class="p">,</span> <span class="s1">'text'</span><span class="p">,)</span>
<span class="n">fallback_values</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'title'</span><span class="p">:</span> <span class="n">_</span><span class="p">(</span><span class="s1">'-- sorry, this news was not translated --'</span><span class="p">),</span>
<span class="s1">'text'</span><span class="p">:</span> <span class="n">_</span><span class="p">(</span><span class="s1">'-- please contact our translator (translator@example.com) --'</span><span class="p">)</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If current language and all fallback languages yield no field value, and no fallback values are
defined, then modeltranslation will use the field’s default value.</p>
</div>
<div class="section" id="fallback-undefined">
<span id="fallback-undef"></span><h3>Fallback undefined<a class="headerlink" href="#fallback-undefined" title="Permalink to this headline">¶</a></h3>
<div class="versionadded">
<p><span class="versionmodified">New in version 0.7.</span></p>
</div>
<p>Another question is what do we consider “no value”, on what value should we fall back to other
translations? For text fields the empty string can usually be considered as the undefined value,
but other fields may have different concepts of empty or missing values.</p>
<p>Modeltranslation defaults to using the field’s default value as the undefined value (the empty
string for non-nullable <code class="docutils literal"><span class="pre">CharFields</span></code>). This requires calling <code class="docutils literal"><span class="pre">get_default</span></code> for every field
access, which in some cases may be expensive.</p>
<p>If you’d like to fall back on a different value or your default is expensive to calculate, provide
a custom undefined value (for a field or model):</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">NewsTranslationOptions</span><span class="p">(</span><span class="n">TranslationOptions</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">(</span><span class="s1">'title'</span><span class="p">,</span> <span class="s1">'text'</span><span class="p">,)</span>
<span class="n">fallback_undefined</span> <span class="o">=</span> <span class="p">{</span>
<span class="s1">'title'</span><span class="p">:</span> <span class="s1">'no title'</span><span class="p">,</span>
<span class="s1">'text'</span><span class="p">:</span> <span class="kc">None</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="the-state-of-the-original-field">
<h2>The State of the Original Field<a class="headerlink" href="#the-state-of-the-original-field" title="Permalink to this headline">¶</a></h2>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.5.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 0.12.</span></p>
</div>
<p>As defined by the <a class="reference internal" href="#rules"><span class="std std-ref">Rules for Translated Field Access</span></a>, accessing the original field is guaranteed to
work on the associated translation field of the current language. This applies
to both, read and write operations.</p>
<p>The actual field value (which <em>can</em> still be accessed through
<code class="docutils literal"><span class="pre">instance.__dict__['original_field_name']</span></code>) however has to be considered
<strong>undetermined</strong> once the field has been registered for translation.
Attempts to keep the value in sync with either the default or current
language’s field value has raised a boatload of unpredictable side effects in
older versions of modeltranslation.</p>
<p>Since version 0.12 the original field is expected to have even more undetermined value.
It’s because Django 1.10 changed the way deferred fields work.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Do not rely on the underlying value of the <em>original field</em> in any way!</p>
</div>
<div class="admonition-todo admonition" id="index-1">
<p class="first admonition-title">Todo</p>
<p class="last">Perhaps outline effects this might have on the <code class="docutils literal"><span class="pre">update_translation_field</span></code>
management command.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Accessing Translated and Translation Fields</a><ul>
<li><a class="reference internal" href="#rules-for-translated-field-access">Rules for Translated Field Access</a></li>
<li><a class="reference internal" href="#examples-for-translated-field-access">Examples for Translated Field Access</a></li>
<li><a class="reference internal" href="#multilingual-manager">Multilingual Manager</a><ul>
<li><a class="reference internal" href="#auto-population">Auto-population</a><ul>
<li><a class="reference internal" href="#auto-population-modes">Auto-population modes</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#falling-back">Falling back</a><ul>
<li><a class="reference internal" href="#fallback-languages">Fallback languages</a></li>
<li><a class="reference internal" href="#fallback-values">Fallback values</a></li>
<li><a class="reference internal" href="#fallback-undefined">Fallback undefined</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-state-of-the-original-field">The State of the Original Field</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="registration.html"
title="previous chapter">Registering Models for Translation</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="forms.html"
title="next chapter">ModelForms</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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="forms.html" title="ModelForms"
>next</a> |</li>
<li class="right" >
<a href="registration.html" title="Registering Models for Translation"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">django-modeltranslation 0.12.2 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2009-2018, Peter Eschler, Dirk Eschler, Jacek Tomaszewski.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|