Macro l10n

macro_rules! l10n {
    ($message_id:tt, $message:tt $(,)?) => { ... };
    ($message_id:tt, $message:tt, $($arg:ident = $arg_expr:expr),* $(,)?) => { ... };
    ($($error:tt)*) => { ... };
}

Gets a variable that localizes and formats the text in a widget context.

Syntax

Macro expects a message key string literal a message template string literal that is also used as fallback, followed by optional named format arguments arg = <arg>,...

The message string syntax is the Fluent Project syntax, interpolations in the form of "{$var}" are resolved to a local $var.

let name = var("World");
let msg = l10n!("file/id.attribute", "Hello {$name}!");

Key

This message key can be just a Fluent identifier, "id", a Fluent attribute identifier can be added "id.attr", and finally a file name can be added "file/id". The key syntax is validated at compile time.

Id

The only required part of a key is the ID, it must contain at least one character, it must start with an ASCII letter and can be followed by any ASCII alphanumeric, _ and -, [a-zA-Z][a-zA-Z0-9_-]*.

Attribute

An attribute identifier can be suffixed on the id, separated by a . followed by an identifier of the same pattern as the id, .[a-zA-Z][a-zA-Z0-9_-]*.

File

An optional file name can be prefixed on the id, separated by a /, it can be a single file name, no extension.

Using the default directory resolver the key "file/id.attr" will search the id and attribute in the file {dir}/{lang}/file.ftl:

id =
    .attr = message

And a key "id.attr" will be searched in the file {dir}/{lang}/_.ftl.

Package

The crate package name and version are also implicitly collected, when the message is requested from a different crate it is searched in {dir}/{lang}/{pkg-name}/{pkg-version}/{file}.ftl. Version matches any other version, the nearest is selected.

Scrap Template

The cargo zng l10n tool can be used to collect all localizable text of Rust code files, it is a text based search that matches this macro name and the two first input literals, avoid renaming this macro to support scrapping, otherwise you will have to declare the template file manually.

The scrapper can also scrap comments, if the previous code line from a l10n! call is a comment starting with prefix l10n-# the text the follows is collected, same for a comment in the same line of the l10n! call. Sections can be declared using l10n-## , all entries after a section comment are added to that section. Standalone notes can be added to the top of the template file from anywhere using l10n-{file_pattern}-### , file pattern can be omitted, l10n-### is equivalent to l10n--### that matches the localization template used when no file is specified.

// l10n-### Standalone Note

// l10n-# Comment for `id`.
let msg = l10n!("id", "id message");

// l10n-# Comment for `id.attr`.
let msg = l10n!("id.attr", "attr message");

// l10n-## Section

let msg = l10n!("other", "other message"); // l10n-# Comment for `other`.

The example above is scrapped to a template.ftl file:

### Standalone Note

# Comment for `id`.
#
# attr:
#     Comment for `id.attr`.
id = id message
    .attr = attr message

## Section

# Commend for `other`.
other = other message

You can install the scraper tool using cargo:

cargo install cargo-zng