.. _doc-i18n:

######################
  Internationalization
######################

:Date: |today|

How to Specify Translation Strings
==================================

Translation strings specify “This text should be translated.”. It’s your responsibility 
to mark translatable strings; the system can only translate strings it knows about.

.. literalinclude:: ../../../../test/snippet/i18n/specify_translation_string.py

The above example translates the given string immediately.  This is not always desired,
since the message catalog might not yet be loaded at the time of execution.  Therefore
translation strings can be specified as lazy.  They will only get translated when they
are used in the GUI.

.. literalinclude:: ../../../../test/snippet/i18n/specify_lazy_translation_string.py

Translation strings in model definitions should always be specified as lazy translation
strings.  Only lazy translation strings can be translated by the end user in various
forms.

How to Create Language Files
============================

Create a message catalog template ::

  pybabel extract -k "tr, _" camelot/ > camelot.pot
  
Create a message catalog

Open message catalog with linguist ::

  linquist camelot.po
  
And edit it :  
  
  .. image:: ../_static/camelot_qt_linguist.png
  
Where to put Translations
=========================

Translations can be put in 2 places :

  * in po files which have to be loaded at application startup
  
  * in the Translation table : this table is editable by the users via the Configuration
    menu.  This is the place to put translations that should be editable by the users.  At
    application startup, all records in this table related to the current language will be 
    put in memory.
  
End user translations
=====================

Often it is convenient to let the end user create or update the translations of an
application, this allows the end user to put a lot of domain knowledge into the application.

Therefore, all lazy translation strings can be translated by the end user.  When the user
right-clicks on a label in a form, he can select 'Change translation' from the menu and
update the current translation (for the current language).  This effectively updates the
content of the 'Translation' table.

After some time the developer can take a copy of this table and decide to put these translations
in po files.