.. _l10n:

===================
Localization (L10n)
===================

Playdoh comes with all the libraries and tools you will need in production
or development for localization.

Localization works by searching for localizable text in your source code and
extracting (or merging them) into `.po` files in `locale/`.


Requirements
------------

The one set of low level tools not provided is ``gettext``.

::

    # for ubuntu/debian
    aptitude install gettext

    # for mac
    brew install gettext


Testing It Out, Right Now
-------------------------

Playdoh comes with a sample app called ``examples`` which is also localized
into French.  This is so that you can get the hang of how things work out of
the box.  To get started, simply follow these quick steps:

#. ``./bin/compile-mo.sh locale/``
#. Set ``DEV=True`` in ``settings/local.py``
#. ``./manage.py runserver``
#. Point your browser to ``http://127.0.0.1:8000/fr``


Installation
------------

If you don't have any localization you need to do the following:

#. ``./manage.py extract -c``
#. ``./manage.py merge -c``

This will populate your ``locale/`` directory.


Usage
-----

Once your directories are set up you'll need to tend to your strings and their
localization.

Strings
~~~~~~~

You can localize strings both in python code as well as Jinja templates.

.. highlight:: python

In python::

  from tower import ugettext as _, ugettext_lazy as _lazy

  yodawg = _lazy('The Internet')

  def myview(request):
      return render('template.html', {msg=_('Hello World'), msg2=yodawg})

.. highlight:: jinja

``_lazy`` is used when we are not in scope of a request.  This lets us evaluate
a string, such as ``yodawg``, at the last possible second when we finally can
draw upon the request's context.  E.g. in a template::

    {{ msg2 }}

Will be evaluated to whatever ``The Internet`` is in the requester's locale.


In Jinja we can use the following syntax for localized strings::


    <h1>{{ _('Hello') }}</h1>

    {% trans link='http://mozilla.org' %}
    <p>Go to this <a href="{{ link }}">site</a>.</p>
    {% endtrans %}


Updating our strings
~~~~~~~~~~~~~~~~~~~~

If you make changes to your strings you can update them::

    ./manage.py extract
    ./manage.py merge

Note: you do not need ``-c`` for either command if you've created the required
directories.


If you want to see these changes in your project::

    ./bin/compile-mo.sh locale/


.. highlight:: python


Creating New Locales
~~~~~~~~~~~~~~~~~~~~

In your projects ``settings.py`` add the new locale to ``KNOWN_LANGUAGES``.

Then run ``./manage.py merge -c`` which will create directories for any locales
that are missing in ``/locale``.


Good Practices
--------------

Let's say you have some template::

    <h1>Hello</h1>

    <p>Is it <a href="http://about.me/lionel.richie">me</a> you're looking for?</p>

Let's say you are told to translate this.  You could do the following::

    {% trans %}
    <h1>Hello</h1>

    <p>Is it <a href="http://about.me/yo">me</a> you're looking for?</p>
    {% endtrans %}

This has a few problems, however:

* It forces every localizer to mimic your HTML, potentially breaking it.
* If you decide to change the HTML, you need to either update your ``.po``
  files or buy all your localizers a nice gift because of all the pain you're
  inflicting upon them.
* If the URL changes, your localizer has to update everything.

Here's an alternative::

    <h1>_('Hello')</h1>

    <p>
      {% trans about_url='http://about.me/lionel.richie' %}
        Is it <a href="{{ about_url }}">me</a> you're looking for?
      {% endtrans %}
    </p>

or if you have multiple paragraphs::

    <h1>_('Hello')</h1>

    {% trans about_url='http://about.me/lionel.richie' %}
      <p>
        Is it <a href="{{ about_url }}">me</a> you're looking for?
      </p>
      <p>
        I can see it in your eyes.
      </p>
    {% endtrans %}

Here are the advantages:

* Localizers have to do minimal HTML.
* The links and even structure of the document can change, but the
  localizations can stay put.

Be mindful of work that localizers will have to do.