#internationalization #translation #l10n #i18n #gettext


Library for localisation (text translation) of Rust applications

3 stable releases

1.0.2 Sep 18, 2020

#29 in Internationalization (i18n)


143 lines


Crates.io Version Docs.rs Version License License

Library for localization (text translation) of Rust applications.


  • Autodetect user's locale (Windows, Unix).

  • Small size - it doesn't depend on regex (like locale_config does).

  • The localization files are embedded in the binary.

  • It looks for localization files in the file system first, so new localization files can be added without application recompilation.

  • It works great with cargo-i18n.

Minimal example:

use translation::{tr_init, tr};

#[folder = "i18n/mo"]
struct Translations;

fn main() {
    tr_init!("locale", Translations);

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

The files from i18n/mo source folder are embedded in the executable file. The tr_init! macro looks for (in the following order):

  • locale/{lang}/LC_MESSAGES/{module_name}.mo in the file system
  • locale/{lang}/{module_name}.mo in the file system
  • {lang}/LC_MESSAGES/{module_name}.mo in the embedded Translations struct
  • {lang}/{module_name}.mo in the embedded Translations struct

The locale folder is looked for relative to the application executable file.


Current solution depends on the following crates:

  • tr - the tr! macro
  • gettext - reimplementation of gettext in Rust
  • rust_embed - to embed locale in executable file

The crate was born because the tr crate (version 0.1.3 at the time of writing) is missing the tr_init! macro when used with gettext crate. Instead of creating pull request for tr crate I started experimenting with new crate and embedding translation files. In the future I plan to add support also for reading .po files directly (so no compilation step of .po files will be required).


Note. This instruction uses cargo-i18 tool. Please also read https://github.com/kellpossible/cargo-i18n for more information.

Configuration Steps

Install required tools:

cargo install xtr
cargo install cargo-i18n

Add the following to your Cargo.toml dependencies:

translation = "1"

Create an i18n.toml file in the root directory of your crate:

fallback_language = "en"

target_languages = ["pl"]
output_dir = "i18n"

Run cargo i18n tool:

cargo i18n

It scans the code and creates and updates the localization file. You can run it every time you want to update your localization files or compile po files.


~56K SLoC