tipfy.ext.i18n¶

This module provides internationalization utilities: a translations store, a middleware to set locale for the current request, functions to manipulate dates according to timezones or translate and localize strings and dates.

Tipfy uses Babel to manage translations of strings and localization of dates and times, and gae-pytz to handle timezones.

See the extension wiki page.

Default configuration¶

tipfy.ext.i18n.default_config¶

Default configuration values for this module. Keys are:

locale

The application default locale code. Default is en_US. timezone: The application default timezone according to the Olson database. Default is America/Chicago.

cookie_name

Cookie name used to save requested locale, in case cookies are used.

locale_request_lookup

A list of tuples (method, key) to search for the locale to be loaded for the current request. The methods are searched in order until a locale is found. Available methods are:

args: gets the locale code from GET arguments.#:
form: gets the locale code from POST arguments.
cookies: gets the locale code from a cookie.
rule_args: gets the locale code from the keywords in the current URL rule.

If none of the methods find a locale code, uses the default locale. Default is [('args', 'lang'), ('cookies', 'tipfy.locale')]: gets the locale from a lang parameter set in GET, and if not set tries to get it from a cookie named tipfy.locale.

date_formats

Default date formats for datetime, date and time.

Translation functions¶

These functions provide functionality to translate strings in templates or in the app code.

tipfy.ext.i18n.get_translations()¶

Returns the current translations object. Forces loading translations for the current request if it was not set already.

Returns:	A `babel.support.Translations` object.

tipfy.ext.i18n.set_translations(locale)¶

Sets the locale and translations object for the current request. Most functions in this module depends on the translations object being set to work properly.

Parameters:	locale – The locale code. For example, `en_US` or `pt_BR`.
Returns:	None.

tipfy.ext.i18n.set_translations_from_request()¶

Sets a translations object for the current request.

It will use the configuration for locale_request_lookup to search for a key in GET, POST, cookie or keywords in the current URL rule. The configuration defines the search order. If no locale is set in any of these, uses the default locale set in config.

By default it gets the locale from a lang GET parameter, and if not set tries to get it from a cookie. This is represented by the default configuration value [('args', 'lang'), ('cookies', 'tipfy.locale')].

Returns:	None.

tipfy.ext.i18n.is_default_locale()¶

Returns True if locale is set to the default locale.

Returns:	True if locale is set to the default locale, False otherwise.

tipfy.ext.i18n.gettext(string, **variables)¶

Translates a given string according to the current locale.

Parameters:	string – The string to be translated. variables – Variables to format the returned string.
Returns:	The translated string.

tipfy.ext.i18n.ngettext(singular, plural, n, **variables)¶

Translates a possible pluralized string according to the current locale.

Parameters:	singular – The singular for of the string to be translated. plural – The plural for of the string to be translated. n – An integer indicating if this is a singular or plural. If greater than 1, it is a plural. variables – Variables to format the returned string.
Returns:	The translated string.

tipfy.ext.i18n.lazy_gettext(string, **variables)¶

A lazy version of [[#gettext]].

Parameters:	string – The string to be translated. variables – Variables to format the returned string.
Returns:	A `babel.support.LazyProxy` object that when accessed translates the string.

tipfy.ext.i18n.lazy_ngettext(singular, plural, n, **variables)¶

A lazy version of [[#ngettext]].

Parameters:	singular – The singular for of the string to be translated. plural – The plural for of the string to be translated. n – An integer indicating if this is a singular or plural. If greater than 1, it is a plural. variables – Variables to format the returned string.
Returns:	A `babel.support.LazyProxy` object that when accessed translates the string.

Date and time functions¶

The preferred way of dealing with dates and times is to always store and work internally with them in UTC, converting to localtime time only when generating output.

UTC is the default timezone in App Engine and is used when auto_now or auto_now_add are set to True in db.Model properties: db.DateProperty, db.DateTimeProperty or db.TimeProperty.

To convert dates and times stored in UTC to a localized version with timezone applied, use the functions format_date(), format_datetime() or format_time().

tipfy.ext.i18n.format_date(date=None, format=None, locale=None, rebase=True)¶

Returns a date formatted according to the given pattern and following the current locale.

Parameters:

date – A date or datetime object. If None, the current date in UTC is used.
format –
The format to be returned. Valid values are “short”, “medium”, “long”, “full” or a custom date/time pattern. Example outputs:
- short: 11/10/09
- medium: Nov 10, 2009
- long: November 10, 2009
- full: Tuesday, November 10, 2009
locale – A locale code. If not set, uses the currently loaded locale.
rebase – If True, converts the date to the currently loaded timezone.

Returns:

A formatted date in unicode.

tipfy.ext.i18n.format_datetime(datetime=None, format=None, locale=None, timezone=None, rebase=True)¶

Returns a date and time formatted according to the given pattern and following the current locale and timezone.

Parameters:

datetime – A datetime object. If None, the current date and time in UTC is used.
format –
The format to be returned. Valid values are “short”, “medium”, “long”, “full” or a custom date/time pattern. Example outputs:
- short: 11/10/09 4:36 PM
- medium: Nov 10, 2009 4:36:05 PM
- long: November 10, 2009 4:36:05 PM +0000
- full: Tuesday, November 10, 2009 4:36:05 PM World (GMT) Time
locale – A locale code. If not set, uses the currently loaded locale.
timezone – The timezone name from the Olson database, e.g.: ‘America/Chicago’. If not set, uses the default returned by get_timezone().
rebase – If True, converts the datetime to the currently loaded timezone.

Returns:

A formatted date and time in unicode.

tipfy.ext.i18n.format_time(time=None, format=None, locale=None, timezone=None, rebase=True)¶

Returns a time formatted according to the given pattern and following the current locale and timezone.

Parameters:

time – A time or datetime object. If None, the current time in UTC is used.
format –
The format to be returned. Valid values are “short”, “medium”, “long”, “full” or a custom date/time pattern. Example outputs:
- short: 4:36 PM
- medium: 4:36:05 PM
- long: 4:36:05 PM +0000
- full: 4:36:05 PM World (GMT) Time
locale – A locale code. If not set, uses the currently loaded locale.
timezone – The timezone name from the Olson database, e.g.: America/Chicago. If not set, uses the default returned by get_timezone().
rebase – If True, converts the time to the currently loaded timezone.

Returns:

A formatted time in unicode.

tipfy.ext.i18n.parse_date(string, locale=None)¶

Parses a date from a string.

This function uses the date format for the locale as a hint to determine the order in which the date fields appear in the string.

>>> parse_date('4/1/04', locale='en_US')
datetime.date(2004, 4, 1)
>>> parse_date('01.04.2004', locale='de_DE')
datetime.date(2004, 4, 1)

Parameters:	string – The string containing the date. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The parsed date object.

tipfy.ext.i18n.parse_datetime(string, locale=None)¶

Parses a date and time from a string.

This function uses the date and time formats for the locale as a hint to determine the order in which the time fields appear in the string.

Parameters:	string – The string containing the date and time. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The parsed datetime object.

tipfy.ext.i18n.parse_time(string, locale=None)¶

Parses a time from a string.

This function uses the time format for the locale as a hint to determine the order in which the time fields appear in the string.

>>> parse_time('15:30:00', locale='en_US')
datetime.time(15, 30)

Parameters:	string – The string containing the time. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The parsed time object.

Number formatting functions¶

tipfy.ext.i18n.format_number(number, locale=None)¶

Returns the given number formatted for a specific locale.

>>> format_number(1099, locale='en_US')
u'1,099'

Parameters:	number – The number to format. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The formatted number.

tipfy.ext.i18n.format_decimal(number, format=None, locale=None)¶

Returns the given decimal number formatted for a specific locale.

>>> format_decimal(1.2345, locale='en_US')
u'1.234'
>>> format_decimal(1.2346, locale='en_US')
u'1.235'
>>> format_decimal(-1.2346, locale='en_US')
u'-1.235'
>>> format_decimal(1.2345, locale='sv_SE')
u'1,234'
>>> format_decimal(12345, locale='de')
u'12.345'

The appropriate thousands grouping and the decimal separator are used for each locale:

>>> format_decimal(12345.5, locale='en_US')
u'12,345.5'

Parameters:	number – The number to format. format – Notation format. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The formatted decimal number.

tipfy.ext.i18n.format_currency(number, currency, format=None, locale=None)¶

Returns a formatted currency value.

>>> format_currency(1099.98, 'USD', locale='en_US')
u'$1,099.98'
>>> format_currency(1099.98, 'USD', locale='es_CO')
u'US$\xa01.099,98'
>>> format_currency(1099.98, 'EUR', locale='de_DE')
u'1.099,98\xa0\u20ac'

The pattern can also be specified explicitly:

>>> format_currency(1099.98, 'EUR', u'\xa4\xa4 #,##0.00', locale='en_US')
u'EUR 1,099.98'

Parameters:	number – The number to format. currency – The currency code. format – Notation format. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The formatted currency value.

tipfy.ext.i18n.format_percent(number, format=None, locale=None)¶

Returns formatted percent value for a specific locale.

>>> format_percent(0.34, locale='en_US')
u'34%'
>>> format_percent(25.1234, locale='en_US')
u'2,512%'
>>> format_percent(25.1234, locale='sv_SE')
u'2\xa0512\xa0%'

The format pattern can also be specified explicitly:

>>> format_percent(25.1234, u'#,##0\u2030', locale='en_US')
u'25,123\u2030'

Parameters:	number – The percent number to format format – Notation format. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The formatted percent number.

tipfy.ext.i18n.format_scientific(number, format=None, locale=None)¶

Returns value formatted in scientific notation for a specific locale.

>>> format_scientific(10000, locale='en_US')
u'1E4'

The format pattern can also be specified explicitly:

>>> format_scientific(1234567, u'##0E00', locale='en_US')
u'1.23E06'

Parameters:	number – The number to format. format – Notation format. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	Value formatted in scientific notation.

tipfy.ext.i18n.parse_number(string, locale=None)¶

Parses localized number string into a long integer.

>>> parse_number('1,099', locale='en_US')
1099L
>>> parse_number('1.099', locale='de_DE')
1099L

When the given string cannot be parsed, an exception is raised:

>>> parse_number('1.099,98', locale='de')
Traceback (most recent call last):
    ...
NumberFormatError: '1.099,98' is not a valid number

Parameters:	string – The string to parse. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The parsed number.
Raises :	`NumberFormatError` if the string can not be converted to a number.

tipfy.ext.i18n.parse_decimal(string, locale=None)¶

Parses localized decimal string into a float.

>>> parse_decimal('1,099.98', locale='en_US')
1099.98
>>> parse_decimal('1.099,98', locale='de')
1099.98

When the given string cannot be parsed, an exception is raised:

>>> parse_decimal('2,109,998', locale='de')
Traceback (most recent call last):
    ...
NumberFormatError: '2,109,998' is not a valid decimal number

Parameters:	string – The string to parse. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The parsed decimal number.
Raises :	`NumberFormatError` if the string can not be converted to a decimal number.

Timezone functions¶

These functions help to convert internal datetime values to different timezones.

tipfy.ext.i18n.get_tzinfo(timezone=None)¶

Returns a datetime.tzinfo object for the given timezone. This is called by [[#format_datetime]] and [[#format_time]] when a tzinfo is not provided.

Parameters:	timezone – The timezone name from the Olson database, e.g.: `America/Chicago`. If not set, uses the default configuration value.
Returns:	A `datetime.tzinfo` object.

tipfy.ext.i18n.to_local_timezone(datetime)¶

Returns a datetime object converted to the local timezone.

This function derives from Kay.

Parameters:	datetime – A `datetime` object.
Returns:	A `datetime` object normalized to a timezone.

tipfy.ext.i18n.to_utc(datetime)¶

Returns a datetime object converted to UTC and without tzinfo.

This function derives from Kay.

Parameters:	datetime – A `datetime` object.
Returns:	A naive `datetime` object (no timezone), converted to UTC.

tipfy.ext.i18n.get_timezone_name(dt_or_tzinfo, locale=None)¶

Returns a representation of the given timezone using “location format”.

The result depends on both the local display name of the country and the city assocaited with the time zone:

>>> from pytz import timezone
>>> tz = timezone('America/St_Johns')
>>> get_timezone_location(tz, locale='de_DE')
u"Kanada (St. John's)"
>>> tz = timezone('America/Mexico_City')
>>> get_timezone_location(tz, locale='de_DE')
u'Mexiko (Mexiko-Stadt)'

If the timezone is associated with a country that uses only a single timezone, just the localized country name is returned:

>>> tz = timezone('Europe/Berlin')
>>> get_timezone_name(tz, locale='de_DE')
u'Deutschland'

Parameters:	dt_or_tzinfo – The `datetime` or `tzinfo` object that determines the timezone; if None, the current date and time in UTC is assumed. locale – A locale code. If not set, uses the currently loaded locale.
Returns:	The localized timezone name using location format.

← tipfy.ext.genshi | tipfy.ext.jinja2 →

tipfy.ext.i18n¶

Default configuration¶

Translation functions¶

Date and time functions¶

Number formatting functions¶

Timezone functions¶

Table Of Contents

All Topics

This Page