A Beginner’s Guide to Python’s locale Module

The locale module is part of the standard built-in module in Python. Explore the key concept behind it, and learn how to use it for string, number, and date formatting.

Python’s locale module is part of the standard library for internationalization (i18n) and localization (l10n) in Python. The locale module allows developers to deal with certain cultural issues in their application. Thereby, they need not know all the specifics of the location or language where the software is used. Let’s explore in great detail the basic concept of Python’s locale module.

The Basics of Python’s locale module

Import and Initialization

Based on the official documentation, the locale module is implemented on top of the _locale module. It uses an ANSI C locale implementation if available. A normal application typically starts with the following code to set the locale:

import locale

# use user's default settings
locale.setlocale(locale.LC_ALL, '')

# use current setting
locale.setlocale(locale.LC_ALL, None)

The first parameter represents the locale category while the second parameter modifies the locale setting for the category. It will use the current setting for the category if the second parameter is not present or None. On the other hand, an empty string will use the user’s default setting.

In the following example, the locale is set to German (de_DE).

# name might vary with operating system, refer to the notes below
locale.setlocale(locale.LC_ALL, 'de_DE')

Most of the time, it uses the Language Code Identifier (LCID) Reference, as stated in the following link (replace the hyphen in the language tags with an underscore). For example, de-DE should be stated as de_DE. However, older OS versions might accept the locale in a different format, as shown below:

# using standard Language Code Identifier (LCID) Reference
locale.setlocale(locale.LC_ALL , 'de_DE')

# using ISO country code, alpha-3
locale.setlocale(locale.LC_ALL , 'deu_deu')

# using language name
locale.setlocale(locale.LC_ALL , 'German')

List of Available Locales

The recommended method is to test out the standard Language Code Identifier Reference first. If you encountered an error, the next step is to print out the full list of the available locales in your machine.

# for Windows users
for lang in locale.windows_locale.values():

# for other operating systems
for lang in locale.locale_alias.values():

Get an Existing Locale

You can get the string for the existing locale with the following code:

# get current locale
loc = locale.getlocale()

Information on an Existing Locale

Calling the built-in localeconv() function will provide you with detailed information on the current locale. Run the following code to visualize it:

for key, value in locale.localeconv().items():
    print("%s: %s" % (key, value))

Here an example output for en_SG (English/Singapore):

Check out the official documentation for more information on the keys and their respective meaning.

Format and Parse Number

The locale module provides two specialized functions to parse a string into a number, based on the current locale:

  • atof (convert a string to a floating point number), and
  • atoi (convert a string to integer).

This is extremely useful for parsing a string that contains a comma or dot, as different locales interpret it differently. For example:

  • 32,824 is 32824.00 for en_SG (English/Singapore),
  • 32,824 is 32.824 for de_DE (German).

On top of that, you can use the format_string() function to format a number according to your preferences. The following code snippet is based on the de_DE locale:

locale.format_string('%10.2f', 738213.78)
# 738213,78

locale.format_string('%10.2f', 738213.78, grouping=True) # grouping is False by default
# 738.213,78

You can set a grouping parameter for the format_string() function, which accepts a boolean.

  • grouping (if set to True, it takes grouping into account; otherwise, it is False by default).

Format Currency

Furthermore, you can utilize the built-in currency() function to format any input number. The end result comes with the currency symbol or text. Let us have a look at the following example for en_SG:

# $924531.78

locale.currency(924531.78, grouping=True)                     
# $924,531.78

locale.currency(924531.78, grouping=True, international=True)
# SGD924,531.78

Apart from the number input, the currency() function also accepts three additional parameters:

  • symbol (if set to True, the returned string includes the currency symbol; the default value is True),
  • grouping (if set to True, the grouping is done with the value; the default value is False),
  • international (if set to True, the international currency symbol is used; the default value is False).

Formatting Date and Time

Other than that, the datetime module helps in formatting date and time, based on the locale that you have set. The easiest way is to rely on the strftime() function. It converts an object to a string according to a given format. It can be a date, time, or datetime object. Let’s have a look at the following list of common format codes

  • %A – weekday as locale’s full name,
  • %b – month as locale’s abbreviated name,
  • %m – month as a zero-padded decimal number,
  • %Y – year with century as a decimal number,
  • %H – hour (24-hour clock) as a zero-padded decimal number,
  • %I – hour (12-hour clock) as a zero-padded decimal number (capital “i”),
  • %p – locale’s equivalent of either AM or PM,
  • %M – minute as a zero-padded decimal number,
  • %S – second as a zero-padded decimal number,
  • %Z – time zone name (empty string if the object is naive).

You can find the full list of format codes in the following link.

Simply define the format in a string, and use it as the input parameter when calling the strftime() function. Check out the following example displaying the current date and time.

now = datetime.datetime.now()
format = "%A, %d %b %Y %H:%M:%S %Z"
# Thursday, 23 July 2020 13:11:31

In addition, you can display just the date component for a specific RSVP event as follows:

registration_date = datetime.date(2020, 8, 15)
format = "RSVP by %A, %d-%b-%Y"

# RSVP by Saturday, 15-Aug-2020

If a value is stored as a timestamp in your database, you can easily convert it to a datetime object:

submission_date = datetime.datetime.fromtimestamp(1595485143)
format = "Submit before %A, %#I%p %d/%m/%Y"
# check notes below

# Submit before Thursday, 2PM 23/07/2020

%I (capital i) represents a 12-hour clock as a zero-padded decimal number. You can remove the leading zero by adding a hyphen or pound sign based on the operating system of your machine. For example,

  • Linux, OS X: %-I
  • Windows, Cygwin: %#I

Besides, you can highlight the timezone as long as the datetime object contains the optimal timezone information. We call this an aware datetime object. In contrast, a naive datetime object does not contain enough information to unambiguously locate itself in relation to other datetime objects. You can easily identify if a datetime object is aware or naive by printing it out.

# naive datetime object, there is no timezone information at the end
2020-08-13 15:14:00.990397

# aware datetime object, using UTC as timezone
2020-08-13 07:14:00.990397+00:00

# aware datetime object, using UTC+6 as timezone
2020-08-13 13:14:00.990397+06:00

For your information, you can easily construct and define a timezone in a datetime object by using datetime.timezone. Let us have a look at the following example of creating instances of current datetime based on different timezones.

format = "Timezone: %H:%M:%S %Z"

# naive datetime object
now = datetime.datetime.now()
# Timezone 15:24:29

# aware datetime object, using UTC as timezone 
now = datetime.datetime.now(tz=datetime.timezone.utc)
# Timezone 07:24:29 UTC

# aware datetime object, using UTC as timezone 
now = datetime.datetime.now(tz=datetime.timezone(datetime.timedelta(hours=6)))
# Timezone 13:24:29 UTC+06:0

%Z will return an empty string, called by a naive datetime object.

Best Practice

Based on the official documentation, the locale module is a program-wide property according to the C standard definition. As a result, it is extremely expensive to change a locale in between.

Frequent locale changes may cause core dumps. That is why it is highly recommended to set it just once while initializing your application.

An extension module or library routine should never call the setlocale() function, since it will affect the entire program.

Apart from the format_string() function, the only way to perform numeric operations according to the locale is to use the special functions defined by this module:

  • atof (convert a string to a floating point number),
  • atoi (convert a string to integer),
  • str (formats a floating point number using the same format as the built-in function str(float) but takes the decimal point into account).

Concluding our Guide to Python’s locale Module

In conclusion, the locale module is extremely useful for internationalizing and localizing Python applications. If you are looking for ways to streamline your i18n process, let Phrase do the heavy lifting. The most reliable translation management platform on the market comes with a 14-day free trial.

Phrase will equip you with everything you need to:

  • Build production-ready integrations with your development workflow,
  • Invite as many users as you wish to collaborate on your projects,
  • Edit and convert localization files online with more context for higher translation quality.

Finally, check out the following articles if you want to know even more about internationalization and localization in Python:

5 (100%) 38 votes

Untangle Continuous Localization With Ease

Get your own FREE EBOOK copy now to explore

  • advanced automation workflows
  • rapid release cycles,
  • simultaneous translation and delivery,
  • new ways of testing your localized product