crowbook-localize 0.1.0

This crate has been renamed crowbook-intl. Please use this one fom now on.

Crate crowbook_localize [] [src]

A library to localize strings, translating them according to runtime options.

Basically, this library allows your project to generate a lformat! macro, that behaves similarly to format!, except the message string (the first argument) might get translated (if you can find the appropriate string for the language).


First, you'll need to add the following to your Cargo.toml file:

build = ""
crowbook-intl = "0.1.0"

crowbook-intl-runtime = "0.1.0"

You'll then need to create the file, which can look like this:

extern crate crowbook_intl;
use crowbook_intl::{Localizer, Extractor};
fn main() {
    // Generate a `lang/default.pot` containing strings used to call `lformat!`
    let mut extractor = Extractor::new();
    extractor.add_messages_from_dir(concat!(env!("CARGO_MANIFEST_DIR"), "/src")).unwrap();
    extractor.write_pot_file(concat!(env!("CARGO_MANIFEST_DIR"), "/lang/default.pot")).unwrap();

    // Generate the `` file
    let mut localizer = Localizer::new(&extractor);
    // Use env::var instead of env! to avoid problems when cross-compiling
    let dest_path = Path::new(&env::var("OUT_DIR").unwrap())

This will create a at build time somewhere in OUT_DIR, containing the lformat! macro. To actually use this macro, you have to create a src/ file that includes it:

include!(concat!(env!("OUT_DIR"), "/"));

//! To use it, the last step is to modify your src/lib/ file:

extern crate crowbook_intl_runtime;
#[macro_use] mod localize_macros;

Once this is done, you can start replacing your calls to format! with calls to lformat!.

In order to get translation, you'll need to actually translate the strings in separate files, and set your to load them.

E.g., if you have the following code:

println!("{}", lformat!("Hello, world!"));

and you want it translated in french, you'll have to create a lang/fr.po file from the lang/default.pot file containing:

msgid "Hello, world!";
msgstr "Bonjour le monde !";

And load it in your file:

let mut localizer = Localizer::new();
localizer.add_lang("fr", include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/lang/"))).unwrap();

Once this is done, you can use the localize_macros::set_lang function to switch the language at runtime:

use crowbook_intl_runtime::set_lang;
println!("{}", lformat!("Hello, world!")); // prints "Hello, world!"
println!("{}", lformat!("Hello, world!")); // prints "Bonjour le monde !"

Updating your translation

When you add new strings that need to be translated (by more calls to lformat!), or when you change the content of existing strings, you can use Gettext's msgmerge and msgcmp commands to update your translation. While it is not guaranteed that the formats are strictly identical, it should work. (That is, it is a bug if it doesn't; but at this stage, this library is absolutely not guaranteed to be bug-free.)


In case the complexity of the operation didn't discourage you, I should warn you that this library is highly experimental at this time.



Error type returned by methods of this library


Struct that extracts all messages from source code and can print them to a .pot file.


Main struct for initiating localization for a project.

Type Definitions


Result type (returned by most methods of this library)