User:Toshio/Python I18N

From FedoraProject

< User:Toshio(Difference between revisions)
Jump to: navigation, search
m (moved ToshioKuratomi/PythonDevelopersGuide to User:Toshio/Python I18N: Take ownership of this and enhance it)
(Link to kitchen; remove draft status)
 
(One intermediate revision by one user not shown)
Line 1: Line 1:
= Collection of Tips for Programming in Python =
+
Setting up and using gettext for i18n can be daunting, not because the code is hard, but because few people have documented how to do it.
  
This page is not a final page.  It is a collection of ideas that need to be vetted and then merged into other documents.
+
== Setup ==
 
+
== i18n ==
+
 
+
=== Setup ===
+
  
 
For an application you can use python's gettext.install to make "_" available as a builtin (and thus available everywhere.)  See the python library documentation for doing that.  For a module, you don't want to pollute the namespace that way.  Instead, in every module, you need to do the following::
 
For an application you can use python's gettext.install to make "_" available as a builtin (and thus available everywhere.)  See the python library documentation for doing that.  For a module, you don't want to pollute the namespace that way.  Instead, in every module, you need to do the following::
Line 17: Line 13:
 
This is a slight variation on what is written in the python library documentation.  Notably, we add <code>fallback=True</code>.  Without that, python will traceback when a locale is used where there is no locale information present.
 
This is a slight variation on what is written in the python library documentation.  Notably, we add <code>fallback=True</code>.  Without that, python will traceback when a locale is used where there is no locale information present.
  
=== Formatting strings ===
+
The [https://fedorahosted.org/releases/k/i/kitchen/docs/api-i18n.html#module-kitchen.i18n kitchen.i18n] module provides a few handy methods for setting this up.  If your code is pretty simple, have a look at [https://fedorahosted.org/releases/k/i/kitchen/docs/api-i18n.html#kitchen.i18n.easy_gettext_setup easy_gettext_setup].  If you have more complex needs, look at [https://fedorahosted.org/releases/k/i/kitchen/docs/api-i18n.html#kitchen.i18n.get_translation_object get_translation_object()]
 +
 
 +
== Formatting strings ==
  
 
It is important when formatting strings that will be localized to use a dictionary for substitution::
 
It is important when formatting strings that will be localized to use a dictionary for substitution::
Line 26: Line 24:
 
name = 'Jamie'
 
name = 'Jamie'
  
 +
# Correct!
 
translatable_string = _('%(name)s is a %(adjective)s %(noun)s') % {'name': name, 'adjective': adjective, 'noun': noun}
 
translatable_string = _('%(name)s is a %(adjective)s %(noun)s') % {'name': name, 'adjective': adjective, 'noun': noun}
  
 +
# Incorrect!
 
translatable_string = _('%s is a %s %s') % (name, adjective, noun)
 
translatable_string = _('%s is a %s %s') % (name, adjective, noun)
 
 
translatable_string = name + _(' is a ') + adjective + ' ' + noun
 
translatable_string = name + _(' is a ') + adjective + ' ' + noun
  

Latest revision as of 01:03, 30 July 2010

Setting up and using gettext for i18n can be daunting, not because the code is hard, but because few people have documented how to do it.

[edit] Setup

For an application you can use python's gettext.install to make "_" available as a builtin (and thus available everywhere.) See the python library documentation for doing that. For a module, you don't want to pollute the namespace that way. Instead, in every module, you need to do the following::

import gettext
translation = gettext.translation('python-fedora', '/usr/share/locale', fallback=True)
_ = translation.ugettext

This is a slight variation on what is written in the python library documentation. Notably, we add fallback=True. Without that, python will traceback when a locale is used where there is no locale information present.

The kitchen.i18n module provides a few handy methods for setting this up. If your code is pretty simple, have a look at easy_gettext_setup. If you have more complex needs, look at get_translation_object()

[edit] Formatting strings

It is important when formatting strings that will be localized to use a dictionary for substitution::

noun = _('rhinoceros')
adjective = _('cranky')
name = 'Jamie'

# Correct!
translatable_string = _('%(name)s is a %(adjective)s %(noun)s') % {'name': name, 'adjective': adjective, 'noun': noun}

# Incorrect!
translatable_string = _('%s is a %s %s') % (name, adjective, noun)
translatable_string = name + _(' is a ') + adjective + ' ' + noun

This is because the translation of the string might need to reorder the words. The dictionary approach to formatting the string allows this but the other two approaches do not.