Macro zng_ext_l10n::l10n
source · macro_rules! l10n { ($message_id:tt, $message:tt $(,)?) => { ... }; ($message_id:tt, $message:tt, $($arg:ident = $arg_expr:expr),* $(,)?) => { ... }; ($($error:tt)*) => { ... }; }
Expand description
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