Skip to content

Python locale Module: Detailed Overview and Examples

The locale module in Python provides access to the cultural and locale-specific conventions of a user's environment. It allows you to format numbers, dates, and currencies according to locale-specific conventions, which is useful for applications that need to be sensitive to regional settings.

Importing the locale Module

To use the functions from the locale module, you need to import it:

import locale

Key Functions and Methods

1. locale.getlocale(category=LC_CTYPE)

Returns the current locale settings for the specified category.

Parameters

  • category: Specifies the category of the locale settings (e.g., locale.LC_CTYPE, locale.LC_NUMERIC, etc.).

Example

import locale

# Get the current locale for numeric category
current_locale = locale.getlocale(locale.LC_NUMERIC)
print(current_locale)  # Output: ('en_US', 'UTF-8')

2. locale.setlocale(category, locale=None)

Sets the locale for the specified category. If locale is None, it returns the current locale setting for the category.

Parameters

  • category: Specifies the category to set (e.g., locale.LC_CTYPE, locale.LC_NUMERIC, etc.).
  • locale: The locale to set (e.g., 'en_US.UTF-8', 'fr_FR').

Example

import locale

# Set the locale for numeric category
locale.setlocale(locale.LC_NUMERIC, 'en_US.UTF-8')

# Get the new locale for numeric category
current_locale = locale.getlocale(locale.LC_NUMERIC)
print(current_locale)  # Output: ('en_US', 'UTF-8')

3. locale.localeconv()

Returns a dictionary containing locale-specific conventions for numeric formatting.

Example

import locale

# Get locale-specific conventions for numeric formatting
conv = locale.localeconv()
print(conv)

Output:

{'decimal_point': '.', 'thousands_sep': ',', 'grouping': [3], 'currency_symbol': '$', 'intl_currency_symbol': 'USD', 'positive_sign': '', 'negative_sign': '-', 'frac_digits': 2, 'p_cs_precedes': 1, 'p_sep_by_space': 0, 'n_cs_precedes': 1, 'n_sep_by_space': 0, 'p_sign_posn': 1, 'n_sign_posn': 1, 'frac_digits': 2, 'p_sign_posn': 1, 'n_sign_posn': 1}

4. locale.format_string(format_string, value, grouping=False)

Formats a number according to the current locale conventions.

Parameters

  • format_string: A format string (e.g., "%f").
  • value: The value to format.
  • grouping: If True, use grouping for thousands.

Example

import locale

# Set locale to German (Germany)
locale.setlocale(locale.LC_NUMERIC, 'de_DE.UTF-8')

# Format a number according to the German locale
formatted_number = locale.format_string("%.2f", 1234567.89, grouping=True)
print(formatted_number)  # Output: '1.234.567,89'

5. locale.currency(value, symbol=True, grouping=False, international=False)

Formats a number as currency according to the current locale conventions.

Parameters

  • value: The value to format.
  • symbol: If True, include the currency symbol.
  • grouping: If True, use grouping for thousands.
  • international: If True, use international currency symbol.

Example

import locale

# Set locale to French (France)
locale.setlocale(locale.LC_MONETARY, 'fr_FR.UTF-8')

# Format a number as currency according to the French locale
formatted_currency = locale.currency(1234567.89, symbol=True, grouping=True)
print(formatted_currency)  # Output: '1 234 567,89 €'

6. locale.strcoll(string1, string2)

Compares two strings according to the current locale conventions.

Parameters

  • string1: The first string to compare.
  • string2: The second string to compare.

Example

import locale

# Set locale to Spanish (Spain)
locale.setlocale(locale.LC_COLLATE, 'es_ES.UTF-8')

# Compare two strings according to the Spanish locale
comparison_result = locale.strcoll('mañana', 'mango')
print(comparison_result)  # Output: Negative number if 'mañana' comes before 'mango'

7. locale.strxfrm(string)

Transforms a string into a format suitable for locale-aware comparisons.

Parameters

  • string: The string to transform.

Example

import locale

# Set locale to Japanese (Japan)
locale.setlocale(locale.LC_COLLATE, 'ja_JP.UTF-8')

# Transform a string for locale-aware comparison
transformed_string = locale.strxfrm('さくら')
print(transformed_string)

8. locale.setlocale(category, locale=None)

Sets the locale for the specified category. If locale is None, it returns the current locale setting for the category.

Example

import locale

# Set the locale for the category LC_TIME
locale.setlocale(locale.LC_TIME, 'fr_FR.UTF-8')

# Get the new locale for time category
current_locale = locale.getlocale(locale.LC_TIME)
print(current_locale)  # Output: ('fr_FR', 'UTF-8')

Locale Categories

The locale module supports several categories that you can set or retrieve:

  • locale.LC_CTYPE: Character classification and case conversion.
  • locale.LC_COLLATE: String collation (sorting and comparison).
  • locale.LC_MONETARY: Formatting of monetary values.
  • locale.LC_NUMERIC: Numeric formatting.
  • locale.LC_TIME: Date and time formatting.

Conclusion

The locale module in Python provides essential functionality for working with locale-specific data formats, such as numbers, dates, and currencies. By setting and retrieving locale information, formatting numbers and currencies, and performing locale-aware string comparisons, you can create applications that are sensitive to regional settings and conventions. This is particularly valuable for internationalized applications and for ensuring that data is presented in a format familiar to users in different locales.