Translating Content
===================

When translating Satchmo to your desired language, you will generally need to translate the words in the templates 
as well as the text used in your product and category descriptions. 
The `Django Internationalization documentation`_ is an excellent resource on the overall capability available 
through Django. The sections below describe the Satchmo specific steps.

Using Transifex
---------------
Satchmo is available on `transifex <http://www.transifex.net>`_ which describes itself as "... an open service allowing people to collaboratively 
translate software, documentation and other types of projects."

This application provides an easy to use web interface for translating Satchmo and submitting the translations
back to Satchmo so they may be incorporated into the application.

The specific Satchmo transifex site is `here. <http://www.transifex.net/projects/p/satchmo/>`_

If you prefer to use your own tools for translation, the sections below describe the steps to generate and maintain
your translations.

Template Translations
---------------------

1. Change to the directory where your Satchmo source is stored (somewhere on your PYTHONPATH). You can run the following
find command to compile all of the langauge files for the satchmo apps::

    find . -name locale -exec sh -c 'cd $0 && cd ../ &&
            /path/to/django-trunk/django/bin/django-admin.py makemessages -l de -e html,txt,rml' {} \;

In the example above, replace "de" with the language code for the message file you want to create.
The language code, in this case, is in locale format. For example, it’s pt_BR for Brazilian
Portuguese and de_AT for Austrian German. The first two letters of the locale is a language code defined
in `ISO 639-1`_ . The second and optional part  consists of an underscore followed by a two letter country code as defined in
`ISO 3166-1`_ . For the command above to work you need to have python and xgettext installed.

This will extract strings that need to be translated from the Satchmo code and templates.
Upon completion of this command these strings along with references to where they are used
are stored in multiple `locale/de/LC_MESSAGES/django.po` (again, replace "de" with your own locale).

If the `django.po` file already exists the above command will update it and
add new strings if any are discovered.

2. Translate the `django.po` file of your locale using a translation editor:

   * `poedit`_
   * `kbabel`_
   * `gtranslator`_

3. After translating the file, you must compile it to an .mo file.  To do this, you must make sure that your local_settings.py file has a LOCALE_PATHS variable defined (it can be a blank string).

4. Compile the file using the compilemessages command (run from your satchmo source directory)::

    find . -name locale -exec sh -c 'cd $0 && cd ../ &&
                                     /path/to/django-admin.py compilemessages' {} \;

5. (Optional but encouraged) Submit a ticket with your translation.

Making a translation available
------------------------------

Django will choose a translation based on the user's browser settings, but this is not always the solution you may be looking for.
To allow users to choose a translation using Satchmo's language selection form, you must add the list of available translations to
your settings.py (or local_settings.py)::

    LANGUAGES = (
                ('en', "English"),
                ('fr', "Français"),
                ('de',"Deutsch"),
                ('es', "Español"),
                ('he',"עִבְרִית"),
                ('it',"Italiano"),
                ('ko', "한국어"),
                ('sv', "Svenska"),
                ('pt-br',"Português"),
                ('bg',"Български"),
                ('tr',"Türkçe"),
                )


Then, edit your settings.py file to enable the i18n urls.::

    #### Satchmo unique variables ####
    from django.conf.urls.defaults import patterns, include
    SATCHMO_SETTINGS = {
        'SHOP_BASE' : '',
        'MULTISHOP' : False,
        'SHOP_URLS' : patterns('', (r'^i18n/', include('l10n.urls')),)
    }

Also, make sure to add 'django.core.context_processors.i18n' to TEMPLATE_CONTEXT_PROCESSORS so that templates will use the 
correct language code.

The default store setup will show the form to allow the store user to select their translation from the above list. If you wish
to disable this option, disable ``allow_translation_choice`` by follow the instructions here :ref:`l10n_settings`. 

Translating dependencies
------------------------

Unless a translation to your language is already available, you may also need to translate packages on which Satchmo depends:

 * `Django`_
 * `Django Registration`_

Such translations are to be submitted to the corresponding project and not to the Satchmo project.

Content Translations
--------------------

After you have translated the templates, you will need to add your translations for the product information. Satchmo has extensive support for multiple languages in your product and category descriptions.

After you have created a product, you can use the Product Translation section to create translated Name, Short Description and Full Description of the product. Creation is straightforward and allows you to version your changes so that you can try different translations to see which is most effective.


.. _Django Internationalization documentation: http://docs.djangoproject.com/en/dev/topics/i18n/
.. _ISO 639-1: http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
.. _ISO 3166-1: http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
.. _Django: http://www.djangoproject.com/
.. _Django Registration: https://bitbucket.org/ubernostrum/django-registration/wiki/Home
.. _poedit: http://www.poedit.net/
.. _kbabel: http://kbabel.kde.org/
.. _gtranslator: http://gtranslator.sourceforge.net/
