Macro gettext_macros::i18n

i18n!() { /* proc-macro */ }

Marks a string as translatable and translate it at runtime.

It add the string to the .pot file and translate them at runtime, using a given gettext::Catalog.

Return value

This macro returns the translated string.

Panics

This macro will panic if it the format string (of the translation) does not match the format arguments that were given. For instance, if you have a string Hello!, that is translated in Esperanto as Saluton {name}!, and that you call this function without any format argument (as expected in the original English string), it will panic.

Examples

Basic usage:

// cat is the gettext::Catalog containing translations for the current locale.
let cat = get_catalog();
i18n!(cat, "Hello, world!");

Formatting a translated string:

let name = "Peter";
i18n!(cat, "Hi {0}!"; name);

// Also works with multiple format arguments
i18n!(cat, "You are our {}th visitor! You won ${}!"; 99_999, 2);

With a context, that will be shown to translators:

let name = "Sophia";
i18n!(cat, context = "The variable is the name of the person being greeted", "Hello, {0}!"; name);

Translating string that changes depending on a number:

let flowers_count = 18;
i18n!(cat, "What a nice flower!", "What a nice garden!"; flowers_count);

With all available options:

let updates = 69;
i18n!(
    cat,
    context = "The notification when updates are available.",
    "There is {} app update available."
    "There are {} app updates available.";
    updates
);

Syntax

This macro expects:

• first, the expression to get the translation catalog to use
• then, optionally, the context named argument, that is a string that will be shown to translators. It should be a str literal, because it needs to be known at compile time.
• the message to translate. It can either be a string literal, or an expression, but if you use the later make sure that the string is correctly added to the .pot file with t.
• if this message has a plural version, it should come after. Here too, both string literals or other expressions are allowed

All these arguments should be separated by commas.

If you want to pass format arguments to this macro, to have them inserted into the translated strings, you should add them at the end, after a colon, and seperate them with commas too.