9 releases
Uses old Rust 2015
0.1.0 | Nov 18, 2016 |
---|---|
0.0.9 | Oct 26, 2016 |
#264 in #internationalization
34KB
613 lines
crowbook-intl
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).
Usage
First, you'll need to add the following to your Cargo.toml
file:
build = "build.rs"
[build-dependencies]
crowbook-localize = "0.0.9"
[dependencies]
lazy_static = "0.2" # the generated file needs `lazy_static!`
You'll then need to create the build.rs
file, which can look like this:
extern crate crowbook_localize;
use crowbook_localize::{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 `localize_macros.rs` file
let mut localizer = Localizer::new(&extractor);
localizer.write_macro_file(concat!(env!("CARGO_MANIFEST_DIR"), "/src/lib/localize_macros.rs")).unwrap();
}
This way, a localize_macros.rs
file will be created at build time in src/lib
.
To use it, the last step is to modify your src/lib/lib.rs
file:
#[macro_use] extern crate lazy_static;
#[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 build.rs
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 build.rs
file:
let mut localizer = Localizer::new();
localizer.add_lang("fr", include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/lang/fr.mp"))).unwrap();
localizer.write_macro_file(concat!(env!("OUT_DIR"), "/localize_macros.rs")).unwrap();
You'll also need to include!
the result of this build script into a localize_macros.rs
file:
include!(concat!(env!("OUT_DIR"), "/localize_macros.rs"));
Once this is done, you can use the localize_macros::set_lang
function
to switch the language at runtime:
use localize_macros::set_lang;
set_lang("en");
println!("{}", lformat!("Hello, world!")); // prints "Hello, world!"
set_lang("fr");
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.)
Warning
In case the complexity of the operation didn't discourage you, I should warn you that this library is highly experimental at this time.
Documentation
See the documentation on docs.rs.
ChangeLog
See the ChangeLog file.
Author
Élisabeth Henry liz.henry@ouvaton.org.
License
This is free software, published under the Mozilla Public License, version 2.0.
Dependencies
~4MB
~78K SLoC