API

class l10n.Locales(*, path: Path | None = None, format: str = '{language}.mo')

Class allowing you to work with compiled (.mo) files collection.

Parameters:

  • path – where compiled locales are located.

  • format – file name template for compiled locales.

get(language: str) → Locale | None

Find locale for the given language.

get_cached(language: str) → Locale | None

The same as get but caches the returned Locale.

property languages: frozenset[str]

List all languages for which a locale is available in the catalog.

property locales: tuple[Locale, ...]

List all locales available in the catalog.

property system_locale: Locale | None

The Locale for the default system language.

property system_language: str | None

The current system language detected from env vars.

class l10n.Locale
reset_cache() → None

Reset all the cached values for the locale object.

Use it if you need to reload the mo file.

get(message: str, *, context: str | None = None, plural: str | None = None, n: int | None = None, comment: str = '') → str

Get translation for the message from the catalog (mo file).

Parameters:

  • message – the message to translate. If no translation found, the message itself will be used. Represented as msgid in PO files.

  • context – kind of namespace for translations, used to distinguish two messages that may have a different translation depending on the context they are used in. Represented as msgctxt in PO files.

  • plural – the default value if n > 1 and no translation found. It also indicates for translator that the message should have plural translations. Represented as msgid_plural in PO files.

  • n – the number used to pick a plural form for the translation.

  • comment – not used in runtime but included in PO files. Use it to provide additional information for translators.

property language: str

The language of the Locale.

format_date(date: date) → str

Format date.

You need the locale do be compiled in your OS.

format_time(time: time) → str

Format time.

You need the locale do be compiled in your OS.

format_datetime(dt: datetime) → str

Format date and time.

You need the locale do be compiled in your OS.

format_month(n: int, *, abbreviate: bool = False) → str

Format the month number into its name.

You need the locale do be compiled in your OS.

format_dow(n: int, *, abbreviate: bool = False, sunday: int = 0) → str

Format the day of week.

You need the locale do be compiled in your OS.

Parameters:

  • abbreviate – Use the short version of the DoW.

  • sunday – Depending on your country and if you count from 0 or 1, different numbers correspond to a different day of week. The sunday argument allows you to specify what number is Sunday for you. By default, it is 0 assuming that the first DoW is Sunday and you count days from 0 to 6.

property currency_symbol: str

The symbol used to denote the currency.

You need the locale do be compiled in your OS.

property decimal_dot: str

The symbol used to separate whole and fractional parts in decimal numbers.

Also known as decimal dot, decimal comma, radix character.

You need the locale do be compiled in your OS.

property thousands_separator: str

The symbol used to separate groups of digits in big numbers.

In most of the languages, it separates groups of three digits. In some locales, though, digits are grouped by 4.

https://en.wikipedia.org/wiki/Decimal_separator

You need the locale do be compiled in your OS.

format_currency(val: int | float | Decimal, *, symbol: bool = True, international: bool = False, grouping: bool = False) → str

Format a price in the locale currency.

  1. The locale currency symbol will be added.

  2. The currency symbol will be placed in the right position.

  3. The minus for negative numbers will be placed in the right position.

  4. The locale decimal separator will be used.

Parameters:

  • symbol – include the currency symbol.

  • international – use international currency symbol.

  • grouping – add thousands separator.

format_float(n: int | float | Decimal, *, grouping: bool = False, monetary: bool = False, precision: int | None = None, strip_zeros: bool | None = None, exp: bool = False) → str

Format float or Decimal with the correct decimal dot.

Parameters:

  • grouping – add thousands separator.

  • monetary – use monetary thousands separator which may be different from a regular one for some locales.

  • precision – if specified, include exactly so many digits in the decimal part.

  • strip_zeros – whatever to remove trailing zeros from the end. If not specified, will be set to True only if precision is not specified.

  • exp – if True, represent large numbers in scientific exponent notation.

format_decimal(n: int | float | Decimal, *, grouping: bool = False, monetary: bool = False, precision: int | None = None, strip_zeros: bool | None = None, exp: bool = False) → str

Format float or Decimal with the correct decimal dot.

Parameters:

  • grouping – add thousands separator.

  • monetary – use monetary thousands separator which may be different from a regular one for some locales.

  • precision – if specified, include exactly so many digits in the decimal part.

  • strip_zeros – whatever to remove trailing zeros from the end. If not specified, will be set to True only if precision is not specified.

  • exp – if True, represent large numbers in scientific exponent notation.

format_int(n: int, grouping: bool = True) → str

Format an integer with grouping (thousands separator).

If you need to show an integer without grouping, you don’t need l10n. All languages display whole numbers in arabic numerals in the same way.

https://en.wikipedia.org/wiki/Arabic_numerals https://en.wikipedia.org/wiki/Decimal_separator

parse_float(s: str) → float

Convert string generated by Locale.format_float back into float.

parse_int(s: str) → int

Convert string generated by Locale.format_int back into int.

translate_country(country_name: str) → str

Translate country name from English to the given language.

Follows ISO 3166-1. Requires iso-codes package to be installed. https://en.wikipedia.org/wiki/ISO_3166-1

translate_currency(currency_name: str) → str

Translate currency name from English to the given language.

Follows ISO 4217. Requires iso-codes package to be installed. https://en.wikipedia.org/wiki/ISO_4217

translate_language(language_name: str) → str

Translate language name from English to the given language.

Follows ISO 639-2 and ISO 639-3. Requires iso-codes package to be installed. https://en.wikipedia.org/wiki/ISO_639-2 https://en.wikipedia.org/wiki/ISO_639-3