Package i18n

Returns a c{List} of valid c{str} locale language / country
codes.  The c{List} is arrange in ascending fallback order.

@return: c{List or c{str} locale language / country codes.

 Retrieves the localized image for the given project.
 The getImage is a convience method that differs from
 getResourceAsStream.

 With getImage no images are registered in the
 resource ini file. Instead a resource directory
 key is registered with a value pointing to
 a directory in the egg containing image resources.

 This path is then searched by the c{I18nManager}
 till an image matching file_name is found
 for the given locale set.

 if fallback was set to False in the c{I18nManager.initialize}
 or the c{I18nManager.setLocale} methods then
 only the first locale in the locale set is
 scanned for an image matching file_name.

 Example resource ini registration:

   [MyProject::all]
   imgs.resources = resource_directory/images/

   [MyProject::fr]
   imgs.resources = locale/fr/resource_directory/images/

 Retrieving the localized image "test.png":

   >>> i18nInstance.setLocaleSet("fr")
   >>> i = i18nInstance.getImage("test.png", "MyProject",
   ...                           "imgs.resources")

The above will first scan the
locale/fr/resource_directory/images/ in the egg
for a file named "test.png". If found a handle to this
file is returned. Otherwise fallback is employed
and the 'all' resource_directory/images/ is searched
for a file named "test.png". If the file is found
a c{file} handle is returned otherwise None.

Once the location of a image is found for the
given localeSet that location is cached so
subsequent requests for the same image do
not result in scanning of the egg for a localized
file name match.

if no project argument is passed the
c{I18nManager._DEFAULT_PROJECT is used.

if no img_dir_name argument is passed the
c{I18nManager._DEFAULT_IMAGE is used.

A sub directory path can alos be past. For example,
a valid file_name can be "my_sub_dir/test.png".
the img_dir_name value will be combined with the file_name
value and the "my_sub_dir" under the img_dir_name
value will be searched for a file named "test.png"

However, this sub directory path must only contain "/"
separators and not Windows "\" separators
as the underlying egg API is platform independent
and does not recognize "\" as a path separator.

The getImage method can raise the following exceptions:
  1. c{UnicodeDecodeError}
  2. c{UnicodeDecodeError}

@param file_name: the file name of the image to
                  retrieve. This image file
                  must be in the same egg as
                  its resource ini definition.

@type file_name: ASCII c{str} or c{unicode}

@param project: A project is a root namespace under which
                resources and localizations exist.

                A project name matches an egg name.
                An egg's info file can contain resource
                and localizations for more than one project.

                The project name must be either an ASCII
                c{str} or c{unicode}. If no project is
                specified the c{I18nManager._DEFAULT_PROJECT}
                is used.


  @type project: ASCII c{str} or c{unicode}

  @param img_dir_name: The named key in a resource ini
                       file whose value points to a
                       directory in the egg that
                       contains image resources.
                       The img_dir_name must be either
                       an ASCII c{str} or c{unicode}.
                       If no img_dir_namme is specified
                       the c{I18nManager._DEFAULT_IMAGE}
                       is used.

  @type img_dir_name: ASCII c{str} or c{unicode}


  @return: An c{file} handle to the image resource or None
 

 Retrieves the localized html for the given project.
 The getHTML is a convience method that differs from
 getResourceAsStream.

 With getHTML no html files are registered in the
 resource ini file. Instead a resource directory
 key is registered with a value pointing to
 a directory in the egg containing html resources.

 This path is then searched by the c{I18nManager}
 till an html file matching file_name is found
 for the given locale set.

 if fallback was set to False in the c{I18nManager.initialize}
 or the c{I18nManager.setLocale} methods then
 only the first locale in the locale set is
 scanned for an html file matching file_name.

 Example resource ini registration:

   [MyProject::all]
   html.resources = resource_directory/html/

   [MyProject::fr]
   html.resources = locale/fr/resource_directory/html/

 Retrieving the localized html "test.html":

   >>> i18nInstance.setLocaleSet("fr")
   >>> h = i18nInstance.getHTML("test.html", "MyProject",
   ...                           "html.resources")

The above will first scan the
locale/fr/resource_directory/html/ in the egg
for a file named "test.html". If found a handle to this
file is returned. Otherwise fallback is employed
and the 'all' resource_directory/html/ is searched
for a file named "test.html". If the file is found
a c{file} handle is returned otherwise None.

Once the location of a html file is found for the
given localeSet that location is cached so
subsequent requests for the same html do
not result in scanning of the egg for a localized
file name match.

if no project argument is passed the
c{I18nManager._DEFAULT_PROJECT is used.

if no html_dir_name argument is passed the
c{I18nManager._DEFAULT_HTML is used.

A sub directory path can alos be past. For example,
a valid file_name can be "my_sub_dir/test.html".
the img_dir_name value will be combined with the file_name
value and the 'my_sub_dir" under the html_dir_name
value will be searched for a file named "test.html"

However, this sub directory path must only contain "/"
separators and not Windows "\" separators
as the underlying egg API is platform independent
and does not recognize "\" as a path separator.

The getHTML method can raise the following exceptions:
  1. c{UnicodeDecodeError}
  2. c{UnicodeDecodeError}

@param file_name: the file name of the html to
                  retrieve. This html file
                  must be in the same egg as
                  its resource ini definition.

@type file_name: ASCII c{str} or c{unicode}

@param project: A project is a root namespace under which
                resources and localizations exist.

                A project name matches an egg name.
                An egg's info file can contain resource
                and localizations for more than one project.

                The project name must be either an ASCII
                c{str} or c{unicode}. If no project is
                specified the c{I18nManager._DEFAULT_PROJECT}
                is used.


  @type project: ASCII c{str} or c{unicode}

  @param html_dir_name: The named key in a resource ini
                       file whose value points to a
                       directory in the egg that
                       contains image resources.
                       The html_dir_name must be either
                       an ASCII c{str} or c{unicode}.
                       If no html_dir_namme is specified
                       the c{I18nManager._DEFAULT_HTML}
                       is used.

  @type html_dir_name: ASCII c{str} or c{unicode}


  @return: An c{file} handle to the html resource or None
 

The c{NoTranslationMessageFactory} method returns the defaultText passed in its original form. No translation is performed.

Chandler translation API. A c{MessageFactory} is leveraged per unique project to access the localization files which are in gettext .mo format.

A unique project can be created per parcel or for a grouping of parcels.

A project is namespace under which translation strings reside.

>>> from i18n import MessageFactory
>>> _ = MessageFactory("myproject")
>>> translatedString = _(u"Some text for translation")

Parameters:

• project (ASCII c{str} or c{unicode}) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII c{str} or c{unicode}.

Returns: function

A MessageFactory.getText function instance

The translation message factory for WxWidgets. The wxMessageFactory is intended as shortcut to allow easy access to translations in the "wxstd" project.

The "wxstd" project must have been loaded by the c{I18nManager} in order to access the translations. Otherwise the defaultText will be returned.

>>> from i18n import wxMessageFactory as w
>>> translatedString = w("Cancel")

Parameters:

• defaultText (ASCII c{str} or c{unicode}) - the unicode or ASCII default key

Returns: unicode

The unicode localized string for key defaultText or the defaultText if no match found

A c{SafeTranslationMessageFactory} is leveraged per unique project to access the localization files which are in gettext .mo format.

A unique project can be created per parcel or for a grouping of parcels.

A project is namespace under which translation strings reside.

Unlike the c{MessageFactory} and c{ChandlerMessageFactory} which will raise an Exception if called before i18n is initialized, A safe translation will return the default text passed in cases where i18n initialization has failed or has not been called.

This method should be used *only* in the cases where a string must be displayed whether i18n has successfully initialized or not.

>>> from i18n import SafeTranslationMessageFactory
>>> _ = SafeTranslationMessageFactory("myproject")
>>> translatedString = _(u"Some text for translation")

Parameters:

• project (ASCII c{str} or c{unicode}) - A project is a root namespace under which resources and localizations exist.

  A project name matches an egg name. An egg's info file can contain resource and localizations for more than one project.

  The project name must be either an ASCII c{str} or c{unicode}.

Returns: function

A SafeTranslationMessageFactory.getText function instance

The translation message factory for Chandler. The ChandlerMessageFactory is intended as shortcut to allow easy access to translations in the "Chandler" project.

A ChandlerMessageFactory example: >>> from i18n import ChandlerMessageFactory as _ >>> translatedString = _(u"Some text for translation")

>>> from i18n import MessageFactory
>>> import i18n
>>> _ = MessageFactory(CHANDLER_PROJECT, DEFAULT_CATALOG)
>>> translatedString = _(u"Some text for translation")

Parameters:

• defaultText (ASCII c{str} or c{unicode}) - the unicode or ASCII default key

Returns: unicode

The unicode localized string for key defaultText or the defaultText if no match found

A safe translation message factory for Chandler. The c{ChandlerSafeTranslationMessageFactory} is intended as shortcut to allow easy access to safe translations in the "Chandler" project.

Unlike the c{MessageFactory} and c{ChandlerMessageFactory} which will raise an Exception if called before i18n is initialized, A safe translation will return the default text passed in cases where i18n initialization has failed or has not been called.

This method should be used *only* in the cases where a string must be displayed whether i18n has successfully initialized or not.

>>> from i18n import ChandlerSafeTranslationMessageFactory as _
>>> translatedString = _(u"Some text for translation")

>>> from i18n import SafeTranslationMessageFactory
>>> _ = SafeTranslationMessageFactory(CHANDLER_PROJECT, DEFAULT_CATALOG)
>>> translatedString = _(u"Some text for translation")

Parameters:

• defaultText (ASCII c{str} or c{unicode}) - the unicode or ASCII default key

Returns: unicode

The unicode localized string for key defaultText or the defaultText if no match found