Skip to content

Locale

Localization and internationalization support for Carbonic.

carbonic.locale

Carbonic localization system.

This module provides comprehensive internationalization support for the Carbonic datetime library, including pluralization rules, number formatting, and localized names for time units, months, and days.

Supported locales: - English (en): Default locale with standard English pluralization - Polish (pl): Complex pluralization rules and Polish translations - Spanish (es): Spanish localization with decimal comma formatting - French (fr): French localization with decimal comma formatting - German (de): German localization with decimal comma formatting - Portuguese (pt): Portuguese localization with decimal comma formatting

Example

from carbonic.locale import get_locale locale = get_locale("pl") locale.get_duration_unit_name("day", 5) 'dni'

Classes

Locale 

Locale(code: str, name: str)

Bases: ABC

Abstract base class for locales.

Functions
pluralize abstractmethod 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

Return the correct plural form based on count and locale rules.

Parameters:

Name Type Description Default
count int | float

The number to use for pluralization

 required
singular str

Singular form (e.g., "day")

 required
plural str

Plural form for 2-4 in languages that have it (e.g., "days")

 required
many str | None

Many form for 5+ in languages that have it (e.g., "days")

 None

Returns:

Type Description
str

The correct plural form
format_number abstractmethod 
format_number(number: float) -> str

Format number according to locale conventions (decimal separator, etc.).

get_duration_unit_name abstractmethod 
get_duration_unit_name(unit: str, count: int | float) -> str

Get the localized name for a duration unit.

Parameters:

Name Type Description Default
unit str

The unit name ("second", "minute", "hour", "day", "week", "month", "year")

 required
count int | float

The count to determine plural form

 required

Returns:

Type Description
str

Localized unit name
get_month_name abstractmethod 
get_month_name(month: int, short: bool = False) -> str

Get localized month name.

Parameters:

Name Type Description Default
month int

Month number (1-12)

 required
short bool

Whether to return short form

 False

Returns:

Type Description
str

Localized month name
get_day_name abstractmethod 
get_day_name(weekday: int, short: bool = False) -> str

Get localized day name.

Parameters:

Name Type Description Default
weekday int

Weekday number (0=Monday, 6=Sunday)

 required
short bool

Whether to return short form

 False

Returns:

Type Description
str

Localized day name

GermanLocale 

GermanLocale()

Bases: Locale

German locale implementation.

Functions
pluralize 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

German pluralization: singular for 1, plural for everything else.

format_number 
format_number(number: float) -> str

Format number using German conventions (decimal comma).

get_duration_unit_name 
get_duration_unit_name(unit: str, count: int | float) -> str

Get German duration unit names with proper pluralization.

get_month_name 
get_month_name(month: int, short: bool = False) -> str

Get German month names.

get_day_name 
get_day_name(weekday: int, short: bool = False) -> str

Get German day names.

EnglishLocale 

EnglishLocale()

Bases: Locale

English locale implementation.

Functions
pluralize 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

English pluralization: singular for 1, plural for everything else.

format_number 
format_number(number: float) -> str

Format number using English conventions (decimal point).

get_duration_unit_name 
get_duration_unit_name(unit: str, count: int | float) -> str

Get English duration unit names with proper pluralization.

get_month_name 
get_month_name(month: int, short: bool = False) -> str

Get English month names using Python's calendar module.

get_day_name 
get_day_name(weekday: int, short: bool = False) -> str

Get English day names using Python's calendar module.

SpanishLocale 

SpanishLocale()

Bases: Locale

Spanish locale implementation.

Functions
pluralize 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

Spanish pluralization: singular for 1, plural for everything else.

format_number 
format_number(number: float) -> str

Format number using Spanish conventions (decimal comma).

get_duration_unit_name 
get_duration_unit_name(unit: str, count: int | float) -> str

Get Spanish duration unit names with proper pluralization.

get_month_name 
get_month_name(month: int, short: bool = False) -> str

Get Spanish month names.

get_day_name 
get_day_name(weekday: int, short: bool = False) -> str

Get Spanish day names.

FrenchLocale 

FrenchLocale()

Bases: Locale

French locale implementation.

Functions
pluralize 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

French pluralization: singular for 1, plural for everything else.

format_number 
format_number(number: float) -> str

Format number using French conventions (decimal comma).

get_duration_unit_name 
get_duration_unit_name(unit: str, count: int | float) -> str

Get French duration unit names with proper pluralization.

get_month_name 
get_month_name(month: int, short: bool = False) -> str

Get French month names.

get_day_name 
get_day_name(weekday: int, short: bool = False) -> str

Get French day names.

PolishLocale 

PolishLocale()

Bases: Locale

Polish locale implementation with complex pluralization rules.

Functions
pluralize 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

Polish pluralization rules: - 1: singular form (1 dzień) - 2-4 (but not 12-14): plural form (2 dni, 3 dni, 4 dni) - 0.5, 1.5, 2.5, etc.: plural form (0,5 sekundy, 1,5 sekundy) - 5+, 0, 12-14: many form (5 dni, 10 dni, 12 dni, 13 dni, 14 dni) - 22, 23, 24, 32, 33, 34, etc.: plural form (22 dni, 23 dni)

format_number 
format_number(number: float) -> str

Format number using Polish conventions (decimal comma).

get_duration_unit_name 
get_duration_unit_name(unit: str, count: int | float) -> str

Get Polish duration unit names with proper pluralization.

get_month_name 
get_month_name(month: int, short: bool = False) -> str

Get Polish month names.

get_day_name 
get_day_name(weekday: int, short: bool = False) -> str

Get Polish day names.

PortugueseLocale 

PortugueseLocale()

Bases: Locale

Portuguese locale implementation.

Functions
pluralize 
pluralize(
    count: int | float, singular: str, plural: str, many: str | None = None
) -> str

Portuguese pluralization: singular for 1, plural for everything else.

format_number 
format_number(number: float) -> str

Format number using Portuguese conventions (decimal comma).

get_duration_unit_name 
get_duration_unit_name(unit: str, count: int | float) -> str

Get Portuguese duration unit names with proper pluralization.

get_month_name 
get_month_name(month: int, short: bool = False) -> str

Get Portuguese month names.

get_day_name 
get_day_name(weekday: int, short: bool = False) -> str

Get Portuguese day names.

Functions

get_locale 

get_locale(code: str | None) -> Locale

Get a locale by code, defaulting to English if None or not found.

Parameters:

Name Type Description Default
code str | None

Locale code (e.g., "en", "pl") or None for default

 required

Returns:

Type Description
Locale

Locale instance

Raises:

Type Description
ValueError

If locale code is not supported

is_locale_available 

is_locale_available(code: str) -> bool

Check if a locale is available.

Parameters:

Name Type Description Default
code str

Locale code (e.g., "en", "pl")

 required

Returns:

Type Description
bool

True if the locale is registered, False otherwise

register_locale 

register_locale(locale: Locale) -> None

Register a locale in the global registry.