Internationalization

Create a locale context for one Citry application.

The application argument keeps the owning engine explicit while hiding the extension-registry lookup needed to reach its i18n extension. The returned context does not change application, task, or process state.

Example

from citry.ext.i18n import make_context

context = make_context(app, locale=request.locale)
html = Page().render(provides={"citry_i18n": context})

Parameters

• app Citry - The Citry application that owns the i18n configuration.
• locale str | None - A configured or inferred source locale, or None to use the configured or inferred default locale.
• time_zone str | None - An IANA time-zone name, or None for a zone-free context.

Returns

LocaleContext: A validated immutable locale context for that application.

Raises

• I18nNotConfiguredError - The application has neither i18n settings nor registered component messages.
• ValueError - A locale or time-zone value is invalid or unavailable.

Own one application's catalog graph, profiles, and locale contexts.

Registered component messages activate the server catalog in source mode. Explicit engine settings additionally activate selectable locales, catalog packages, named profiles, parsing, and browser delivery.

Application code normally obtains this built-in extension from app.extensions.get_extension("i18n"). Create a context with make_context(), pass it through root render(provides={"citry_i18n": context}), and use for_context() outside components. Components receive the same operations through self.i18n.

commands: list[type[ExtensionCommand]]

configured: bool

available: bool

config: I18nEngineConfig

catalog_revision: str

urls: list[URLRoute]

context: LocaleContext

context_for_component(component: Component) -> LocaleContext

format_for_component(component: Component, usage: I18nUsageCollector | None = None) -> I18nFormatter

parse_for_component(component: Component, usage: I18nUsageCollector | None = None) -> I18nParser

for_context(context: LocaleContext) -> I18nService

validate_config_fields(fields: Mapping[str, Any], component: type[Component] | None = None) -> None

on_extension_created(ctx: OnExtensionCreatedContext) -> None

on_messages_loaded(ctx: OnMessagesLoadedContext) -> str | None

on_files_reset(_ctx: OnFilesResetContext) -> None

on_component_registered(ctx: OnComponentRegisteredContext) -> None

on_component_unregistered(ctx: OnComponentUnregisteredContext) -> None

on_citry_cleared(ctx: OnCitryClearedContext) -> None

inspect_template_namespace(ctx: TemplateNamespaceContext) -> TemplateNamespaceContribution | None

on_component_data(ctx: OnComponentDataContext) -> None

on_template_compiled(ctx: OnTemplateCompiledContext) -> list[Any]

on_component_rendered(ctx: OnComponentRenderedContext) -> None

on_render_context_merge(ctx: OnRenderContextMergeContext) -> None

on_dependencies(ctx: OnDependenciesContext) -> None

export_render_cache(ctx: OnRenderCacheExportContext) -> dict[str, object]

stage_render_cache(ctx: OnRenderCacheStageContext) -> StagedRenderCacheContribution

make_context(locale: str | None = None, time_zone: str | None = None) -> LocaleContext

browser_artifact(locale: str, outputs: tuple[MessageOutputUse, ...] | tuple[str, ...], messages: tuple[str, ...]) -> dict[str, object]

browser_parser_artifact(locale: str) -> dict[str, object]

tr(message_id: str, attr: str | None = None, context: LocaleContext | None = None, **values: object = {}) -> str

resolve(message_id: str, attr: str | None = None, context: LocaleContext | None = None, **values: object = {}) -> LocalizedText

resolve_rich(message_id: str, values: Mapping[str, object], slots: Mapping[str, object], attr: str | None = None, context: LocaleContext | None = None) -> dict[str, object]

Per-component i18n settings and access to the provided locale context.

Set Component.I18n.messages_locale to the locale in which that component's messages / messages_file source is authored. Declaring a message asset activates server translations even when the engine has no i18n settings. Declare client_messages only for finite dynamic message IDs that static browser analysis cannot see. Instances expose the nearest explicit context, translation, formatting, and parsing through self.i18n.

messages_locale: str | None

client_messages: tuple[str, ...]

configured: bool

available: bool

context: LocaleContext

tr(message_id: str, attr: str | None = None, **values: object = {}) -> str

resolve(message_id: str, attr: str | None = None, **values: object = {}) -> LocalizedText

format: I18nFormatter

parse: I18nParser

Use messages, formatting, and parsing with one explicit locale context.

Create this service with I18nExtension.for_context. Components receive the same operations through Component.i18n.

Attributes

• context LocaleContext - The exact locale context used by every operation.
• format I18nFormatter - Named formatting operations bound to context.
• parse I18nParser - Strict parsing operations bound to context.

configured: bool

available: bool

context: LocaleContext

tr(message_id: str, attr: str | None = None, **values: object = {}) -> str

resolve(message_id: str, attr: str | None = None, **values: object = {}) -> LocalizedText

format: I18nFormatter

parse: I18nParser

Format canonical values with one component or locale context.

Citry creates this object for I18n.format and I18nService.format. Application code should use those entry points rather than constructing it directly.

number(value: int | Decimal, format: str) -> str

percent(value: int | Decimal, format: str) -> str

currency(value: int | Decimal, currency: str, format: str) -> str

date(value: date, format: str) -> str

time(value: time, format: str) -> str

datetime(value: datetime, format: str) -> str

relative_time(value: int | Decimal, unit: str, format: str) -> str

list(values: object, format: str) -> str

unit(value: int | Decimal, unit: str, format: str) -> str

Parse localized edits with one component or locale context.

Citry creates this object for I18n.parse and I18nService.parse. Application code should use those entry points rather than constructing it directly.

number(input: str, format: str) -> NumberParseResult

percent(input: str, format: str) -> PercentParseResult

date(input: str, format: str) -> DateParseResult

date_segments(input: DateSegments, format: str) -> DateParseResult

time(input: str, format: str) -> TimeParseResult

time_segments(input: TimeSegments, format: str) -> TimeParseResult

datetime(input: str, format: str, fold: str | None = None) -> DateTimeParseResult

datetime_segments(input: DateTimeSegments, format: str, fold: str | None = None) -> DateTimeParseResult

All explicit render inputs that can change localized output.

Attributes

• locale str - The selected canonical locale.
• fallback_locales tuple[str, ...] - The ordered configured fallback chain.
• direction Literal['ltr', 'rtl'] - The writing direction used by the render subtree.
• time_zone str | None - The explicit IANA time zone, or None for zone-free work.
• tzdb_revision str - The exact time-zone data revision.
• catalog_revision str - The exact checked message graph revision.
• formats_revision str - The exact named-profile registry revision.

locale: str

fallback_locales: tuple[str, ...]

direction: Literal['ltr', 'rtl']

time_zone: str | None

tzdb_revision: str

catalog_revision: str

formats_revision: str

identity: tuple[object, ...]

Resolved text plus the locale metadata needed by semantic wrappers.

Attributes

• text str - The formatted message text.
• locale str - The locale that supplied the selected pattern.
• direction Literal['ltr', 'rtl'] - The selected pattern's writing direction.
• used_fallback bool - Whether resolution used a locale other than the request.

text: str

locale: str

direction: Literal['ltr', 'rtl']

used_fallback: bool

Store the application's named formatter profiles.

The profile names are application-defined. Each value uses one of Citry's checked profile types so the Rust server and browser can share the same contract.

Example

Give call sites names that describe why they format a value::

formats = FormatRegistry(
    number={
        "measurement": NumberFormat(),
    },
    date={
        "invoice-date": DateFormat(
            length="long",
        ),
    },
)

# Inside a component:
text = self.i18n.format.number(
    meters,
    format="measurement",
)

Attributes

• number Mapping[str, NumberFormat] - Exact-decimal number profiles.
• percent Mapping[str, PercentFormat] - Ratio-based percent profiles and their input rules.
• currency Mapping[str, CurrencyFormat] - Currency profiles.
• date Mapping[str, DateFormat] - Calendar-date profiles.
• time Mapping[str, TimeFormat] - Wall-clock time profiles.
• datetime Mapping[str, DateTimeFormat] - Instant and time-zone profiles.
• relative_time Mapping[str, RelativeTimeFormat] - Relative-time profiles.
• list Mapping[str, ListFormat] - Conjunction and disjunction list profiles.
• unit Mapping[str, UnitFormat] - Standalone measurement-unit profiles.

number: Mapping[str, NumberFormat]

percent: Mapping[str, PercentFormat]

currency: Mapping[str, CurrencyFormat]

date: Mapping[str, DateFormat]

time: Mapping[str, TimeFormat]

datetime: Mapping[str, DateTimeFormat]

relative_time: Mapping[str, RelativeTimeFormat]

list: Mapping[str, ListFormat]

unit: Mapping[str, UnitFormat]

to_wire() -> dict[str, dict[str, dict[str, object]]]

revision: str

Use ICU4X's locale-default exact-decimal format and input grammar.

input: NumberInput

Declare the strict notation accepted by a named number profile.

notation: Literal['decimal', 'decimal_or_scientific']

One strict localized number edit without losing unfinished text.

Attributes

• input str - The exact user edit.
• state Literal['valid', 'incomplete', 'invalid'] - valid, incomplete, or invalid.
• value Decimal | None - The canonical exact decimal when valid.
• error str | None - A stable explanation for an invalid result, otherwise None.

input: str

state: Literal['valid', 'incomplete', 'invalid']

value: Decimal | None

error: str | None

valid: bool

Format a canonical ratio and optionally accept localized percent edits.

A value of Decimal("0.125") represents 12.5 percent. Parsing returns the same ratio domain value.

Attributes

• input PercentInput - The strict editing rule used by i18n.parse.percent().

input: PercentInput

Choose whether a percent edit includes the locale's percent affix.

Attributes

• affix Literal['required', 'omit'] - "required" accepts the same affix that formatting emits. "omit" accepts only the localized number, which is useful when a control renders the affix outside its editable field.

affix: Literal['required', 'omit']

Keep one localized percent edit and its canonical ratio separate.

Attributes

• input str - The exact user edit.
• state Literal['valid', 'incomplete', 'invalid'] - valid, incomplete, or invalid.
• value Decimal | None - The canonical ratio when valid; 0.125 means 12.5 percent.
• error str | None - A stable explanation for an invalid result, otherwise None.

input: str

state: Literal['valid', 'incomplete', 'invalid']

value: Decimal | None

error: str | None

valid: bool

Use ICU4X's checked locale-default currency format.

Format a date and optionally accept input through the same profile.

Attributes

• length Literal['short', 'medium', 'long'] - The locale-sensitive display length.
• input DateInput | None - The strict editing rule. None keeps the profile display-only.

length: Literal['short', 'medium', 'long']

input: DateInput | None

Declare how a named date profile accepts editable input.

Attributes

• mode Literal['strict_text', 'segments'] - "strict_text" accepts one localized date string. "segments" accepts named year, month, and day edit segments.
• two_digit_year_start int | None - The first year in the selected calendar's explicit 100-year window. None requires a full year.

mode: Literal['strict_text', 'segments']

two_digit_year_start: int | None

Hold the three editable fields from a segmented date control.

Attributes

• year str - The localized calendar-year edit.
• month str - The localized numeric month edit.
• day str - The localized day-of-month edit.

year: str

month: str

day: str

Keep one localized date edit and its canonical Python date separate.

ambiguous reports an input that needs an explicit calendar decision. valid is the only state with a canonical value.

input: str | DateSegments

state: Literal['valid', 'incomplete', 'invalid', 'ambiguous']

value: date | None

error: str | None

valid: bool

Format a wall-clock time and optionally accept localized edits.

Attributes

• length Literal['short', 'medium', 'long'] - The locale-sensitive display length.
• input TimeInput | None - The strict editing rule. None keeps the profile display-only.

length: Literal['short', 'medium', 'long']

input: TimeInput | None

Declare how a named wall-clock time profile accepts editable input.

strict_text accepts one locale-shaped string. segments accepts a TimeSegments value from a segmented control.

mode: Literal['strict_text', 'segments']

Hold editable fields from a segmented wall-clock time control.

second and day_period are optional because the named profile decides whether those fields are present.

hour: str

minute: str

second: str | None

day_period: str | None

Keep one localized time edit and its canonical wall-clock value separate.

The result is a zone-free datetime.time. Converting it to an instant requires a date and time zone.

input: str | TimeSegments

state: Literal['valid', 'incomplete', 'invalid']

value: time | None

error: str | None

valid: bool

Format an instant after conversion to the context's explicit IANA zone.

Attributes

• length Literal['short', 'medium', 'long'] - The locale-sensitive date and time display length.
• time_zone_name Literal['none', 'short', 'long'] - Whether and how to display the resolved zone name.
• input DateTimeInput | None - The strict local-edit rule. None keeps the profile display-only.

length: Literal['short', 'medium', 'long']

time_zone_name: Literal['none', 'short', 'long']

input: DateTimeInput | None

Declare how a named local datetime profile accepts editable input.

Attributes

• mode Literal['strict_text', 'segments'] - strict_text for one string or segments for named fields.
• two_digit_year_start int | None - First year in an explicit 100-year window, or None to require a full year.

mode: Literal['strict_text', 'segments']

two_digit_year_start: int | None

Combine named date and time fields from one local datetime control.

date: DateSegments

time: TimeSegments

Keep a local datetime edit separate from its resolved aware instant.

An ambiguous daylight-saving fold returns both aware instants in alternatives. Pass fold="earlier" or fold="later" to the parser to resolve that choice explicitly.

input: str | DateTimeSegments

state: Literal['valid', 'incomplete', 'invalid', 'ambiguous']

value: datetime | None

error: str | None

alternatives: tuple[datetime, ...]

valid: bool

Format a relative day count; the current checked unit is day.

unit: Literal['day']

Format a conjunction or disjunction list.

kind chooses “and” or “or”. length chooses the locale's wide, short, or narrow pattern.

kind: Literal['and', 'or']

length: Literal['wide', 'short', 'narrow']

Format an exact value with an explicit CLDR unit identifier.

Attributes

• width Literal['long', 'short', 'narrow'] - How fully ICU4X writes the unit name.

width: Literal['long', 'short', 'narrow']

Base class for i18n errors.

Raised when an i18n operation needs settings or messages that are absent.

Raised when the requested i18n operation cannot run in the current context.