Crate message_format [−] [src]

Message Format

A Message is a piece of user-visible text that typically has variable elements.

Often, when writing your application, you need to customize the output based on various variable values:

Your search had no results.
Your search had one result.
Your search had 3 results.

You don't want to have specific code for each message output to build up the text, and ideally, you'll be supporting localization so that your application can be used by people who speak other languages, which often have different rules concerning pluralization, gender and list formatting.

Using the ICU Message Format syntax supported by this library, the above text would be generated by this message (in English):

{count, plural,
  =0 {Your search had no results.}
  =1 {Your search had one result.}
  other {Your search had # results.}}

Assuming you had that parsed into a message search_results, the code to format that might look like:

let s = format_message!(ctx, search_results, count => results.len());

Other languages with different rules for plurals, gender and other things can have correct output just by updating the message text without having to modify the code.

Separating messages from the code has other benefits as well apart from making localization easier. You may need different branding of your product for different builds, or you may want to be able to have someone edit and proofread the text without having to have them modify the code itself.

This module currently provides support for messages using the ICU Message Format. In the future, we will support the L20n message format as well.

Installation

This crate works with Cargo and is on crates.io. Add it to your Cargo.toml like so:

[dependencies]
message-format = "0.0.1"

This library depends upon some macros being used, so at the top of your crate, you will want to make sure that macros from this crate are used:

#[macro_use]
extern crate message_format;

Contexts

The context stores information that is shared between all of the formats that are formatted using that context. (You might want to have multiple contexts, or you might not.)

For now, this stores the locale that is being used, but in the future, it will be used for additional features.

ICU Formatted Messages

The simplest way to create an ICU formatted Message from code is to parse it from a text format:

use message_format::icu;

let m = icu::parse("Connecting to {host}...").unwrap();

For details on the ICU Message Format syntax, see the icu module.

L20n Formatted Messages

Support for the L20n localization format is under development.

Formatting a Message

Messages need arguments or parameters. Since messages typically have named arguments, we can't just pass arguments directly like we might do with format! or other lower level formatting operations. Instead, we have our own macros.

Arguments can be specified as name => value or, if you have a variable with the same name as the argument already, then as just name.

#[macro_use]
extern crate message_format;

fn main() {
    let ctx = message_format::Context::default();
    let m1 = message_format::icu::parse("Connecting to {host}...").unwrap();
    assert_eq!(format_message!(ctx, &m1, host => "localhost"),
               "Connecting to localhost...");

    let m2 = message_format::icu::parse("{name} went to {place}.").unwrap();
    let name = "Jacob";
    assert_eq!(format_message!(ctx, &m2, name, place => "the store"),
               "Jacob went to the store.");
}

Future Directions

In the future, we want to extend this library to support a number of additional features:

Serializing and deserializing messages in a binary format to avoid needing to parse them on every application startup.
Integration with rust-locale or other libraries for doing locale specific formatting.
Extending the types of data that can be used with Value.
Supporting L20n and perhaps other message format syntaxes. (This will probably require API changes.)
Offline utilities for compiling and validating message format strings, converting to and from various formats like XLIFF, etc.

Contributions

Contributions are welcome.

Modules

icu	ICU Message Format Support
l20n

Macros

format_message!
message_args!
message_args_aux!
write_message!

Structs

Args	Holds the arguments being used to format a `Message`.
Context	Contextual configuration data.
Message	A message that has been localized and can be formatted in a locale-aware manner.

Enums

PluralCategory	The set of grammatical numbers that we support.
Value	A wrapper around a value, used with `Args` so that a `MessagePart` can access the original value when necessary.

Traits

MessagePart

Part of a message. May be something that requires formatting a value or just plain text.

Functions

arg	Create an argument holder.
english_cardinal_classifier	English cardinal plural classifier.