Struct Locale 

pub struct Locale {

    pub locale: String,
    pub dates: DateTerms,
    pub roles: HashMap<ContributorRole, ContributorTerm>,
    pub locators: HashMap<LocatorType, LocatorTerm>,
    pub terms: Terms,
    pub punctuation_in_quote: bool,
    pub sort_articles: Vec<String>,
    pub locale_schema_version: Option<String>,
    pub evaluation: EvaluationConfig,
    pub messages: HashMap<String, String>,
    pub date_formats: HashMap<String, String>,
    pub number_formats: NumberFormats,
    pub grammar_options: GrammarOptions,
    pub legacy_term_aliases: HashMap<String, String>,
    pub vocab: VocabMap,
    pub evaluator: Arc<dyn MessageEvaluator>,
}

A locale definition containing language-specific terms and formatting rules.

The evaluator field holds the message evaluation engine, selected based on evaluation.message_syntax. This allows for trait-based swapping to ICU4X implementations in the future without changing call sites.

Fields

locale: String

The locale identifier (e.g., “en-US”, “de-DE”).

dates: DateTerms

Date-related terms (months, seasons).

roles: HashMap<ContributorRole, ContributorTerm>

Contributor role terms (editor, translator, etc.).

locators: HashMap<LocatorType, LocatorTerm>

Locator terms (page, chapter, etc.).

terms: Terms

General terms (and, et al., etc.).

punctuation_in_quote: bool

Whether to place periods/commas inside quotation marks. true = American style (“text.”), false = British style (“text”.)

sort_articles: Vec<String>

Articles to strip from titles when sorting (e.g., “the”, “a”, “an” for English). These should be lowercase and will be matched case-insensitively.

locale_schema_version: Option<String>

Schema version from the source locale file (None = legacy v1).

evaluation: EvaluationConfig

Runtime evaluation configuration.

messages: HashMap<String, String>

ICU MF1 messages keyed by message ID (populated for v2 locales).

date_formats: HashMap<String, String>

Named date format presets: symbolic name → CLDR pattern.

number_formats: NumberFormats

Number formatting options.

grammar_options: GrammarOptions

Grammar options.

legacy_term_aliases: HashMap<String, String>

Backwards-compatibility aliases: old term key → new message ID.

vocab: VocabMap

Vocabulary maps for genre and medium display text.

evaluator: Arc<dyn MessageEvaluator>

Message evaluator implementation (not serialized; set during load).

Implementations

impl Locale

pub fn from_yaml_str(yaml: &str) -> Result<Locale, String>

Load a locale from a YAML string.

Errors

Returns an error when the YAML cannot be parsed into a locale.

pub fn load(locale_id: &str, locales_dir: &Path) -> Locale

Load a locale by ID (e.g., “en-US”, “de-DE”) from a locales directory. Falls back to en-US if the locale file is not found.

pub fn from_file(path: &Path) -> Result<Locale, String>

Load locale from a file path directly (detects format).

Errors

Returns an error when the file cannot be read or its contents cannot be parsed as a supported locale format.

pub fn parse_general_term(name: &str) -> Option<GeneralTerm>

Parse a locale term key into a structured general-term identifier.

pub fn apply_override(&mut self, ov: &LocaleOverride)

Apply a partial override, merging its fields into this locale.

Performs key-by-key insertion or replacement for:

• messages: new or updated message IDs
• grammar_options: if Some, replaces the entire block and syncs punctuation_in_quote field
• legacy_term_aliases: new or updated term aliases

impl Locale

pub fn en_us() -> Locale

Create a new English (US) locale with default terms.

pub fn strip_sort_articles<'a>(&self, s: &'a str) -> &'a str

Strip leading articles from a string for sorting.

Uses locale-specific articles (e.g., “the”, “a”, “an” for English; “der”, “die”, “das” for German). Falls back to English articles if no locale-specific articles are defined.

pub fn lookup_genre(&self, key: &str) -> String

Look up display text for a genre canonical key.

Falls back to a readable form of the key if no translation found.

pub fn lookup_medium(&self, key: &str) -> String

Look up display text for a medium canonical key.

Falls back to a readable form of the key if no translation found.

pub fn role_term( &self, role: &ContributorRole, plural: bool, form: &TermForm, requested_gender: Option<GrammaticalGender>, ) -> Option<&str>

Get a contributor role term.

pub fn role_term_neutral( &self, role: &ContributorRole, plural: bool, form: &TermForm, ) -> Option<&str>

Resolve a contributor role term using only neutral/common values.

pub fn resolved_role_term( &self, role: &ContributorRole, plural: bool, form: &TermForm, requested_gender: Option<GrammaticalGender>, ) -> Option<String>

Resolve a contributor role term, evaluating MF2 messages when configured.

pub fn resolved_role_term_neutral( &self, role: &ContributorRole, plural: bool, form: &TermForm, ) -> Option<String>

Resolve a contributor role term using only neutral/common values.

pub fn locator_term( &self, locator: &LocatorType, plural: bool, form: &TermForm, requested_gender: Option<GrammaticalGender>, ) -> Option<&str>

Get a locator term.

pub fn resolved_locator_term( &self, locator: &LocatorType, plural: bool, form: &TermForm, requested_gender: Option<GrammaticalGender>, ) -> Option<String>

Resolve a locator term, evaluating MF2 messages when configured.

pub fn general_term( &self, term: &GeneralTerm, form: &TermForm, requested_gender: Option<GrammaticalGender>, ) -> Option<&str>

Resolve a general term to a borrowed string.

pub fn resolved_general_term( &self, term: &GeneralTerm, form: &TermForm, requested_gender: Option<GrammaticalGender>, ) -> Option<String>

Resolve a general term, evaluating MF2 messages when configured.

pub fn resolved_archive_term( &self, field: ArchiveHierarchyField, ) -> Option<String>

Resolve an archive hierarchy label, using MF2 messages. Returns singular form (count=1) by default.

pub fn and_term(&self, use_symbol: bool) -> &str

Get the “and” term based on style preference.

pub fn et_al(&self) -> &str

Get the “et al.” term.

pub fn month_name(&self, month: u8, short: bool) -> &str

Get a month name.

pub fn resolve_date_pattern( &self, message_id: &str, year: Option<&str>, month: Option<&str>, day: Option<u32>, ) -> Option<String>

Resolve a pattern.date-* message with locale-specific year/month/day components.

Returns Some(rendered) only when the locale carries an MF2 message at message_id and the evaluator produces output. Callers fall back to the engine’s hardcoded English assembly on None.

A component is forwarded to the evaluator only when non-empty; an authored pattern that references {$day} therefore yields None if the input date carries no day, letting the caller pick a shorter form.

The day argument is taken as Option<u32> rather than a pre-formatted string so the digit-to-string allocation is deferred until after the message lookup succeeds — the common case for legacy locales (en-US, every v1 file) is the lookup miss, which now incurs zero allocation.

Trait Implementations

impl Clone for Locale

fn clone(&self) -> Locale

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Locale

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Locale

fn default() -> Locale

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Locale

fn deserialize<__D>( __deserializer: __D, ) -> Result<Locale, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Locale

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.