This crate is a Cargo sub-command cargo i18n which can be used to extract and
build, and verify localization resources at compile time for your crate. The
i18n-embed library has been created to
allow you to conveniently embed these localizations into your application or
library, and have them selected at runtime. Different systems can be used simultaneously.
i18n-embed supports both the following localization systems:
You can install this tool using the command: cargo install cargo-i18n.
The cargo i18n command reads the configuration file (by default called i18n.toml) in the root directory of your crate, and then proceeds to extract localization resources from your source files, and build them.
The i18n-build library contains most of the implementation for this tool. It has been published separately to allow its direct use within project build scripts if required.
Fluent support is now available in i18n-embed. See the examples for that crate, and the documentation for i18n-embed for example of how to use it.
See also the fl!() macro for a convenient compile-time checked way to access fluent messages when using i18n-embed.
Currently there are no validations performed by the cargo-i18n tool when using the fluent localization system, however there are some planned (see tracking issue #31). If you have any more ideas for this, please feel free to contribute to the issue discussion.
This is an example for how to use the cargo-i18n tool, and i18n-embed the gettext localization tool system. Please note that the gettext localization system is technically inferior to fluent in a number of ways, however there are always legacy reasons, and the developer/translator ecosystem around gettext is more mature.
Firstly, ensure you have the required utilities installed on your system. See Gettext System Requirements and install the necessary utilities and commands for the localization system you will be using.
You will need to ensure that your strings in your source code that you want localized are using the tr!() macro from the tr crate.
You can add comments to your strings which will be available to translators to add context, and ensure that they understand what the string is for.
For example:
```rust use tr::tr;
fn example(file: String) { let my_string = tr!( // {0} is a file path // Example message: Printing this file: "file.doc" "Printing this file: \"{0}\"", file ); } ```
You will need to create an i18n.toml configuration in the root directory of your crate. A minimal configuration for a binary crate to be localized to Spanish and Japanese using the gettext system would be:
```toml
fallback_language = "en"
[gettext]
target_languages = ["es", "ja"]
i18n.toml of the crateoutput_dir = "i18n" ```
See Configuration for a description of all the available configuration options.
cargo i18nOpen your command line/terminal and navigate to your crate directory, and run cargo i18n. You may be prompted to enter some email addresses to use for contact points for each of the language's po files. At the end there should be a new directory in your crate called i18n, and inside will be pot, po and mo directories.
The pot directory contains pot files which were extracted from your source code using the xtr tool, and there should be a single pot file with the name of your crate in here too, which is the result of merging all the other pot files.
The po directory contains the language specific message files.
The mo directory contains the compiled messages, which will later be embedded into your application.
At this point it could be a good idea to add the following to your crate's .gitignore (if you are using git):
gitignore
/i18n/pot
/i18n/mo
If you want your crate to be able to build without requiring this tool to be present on the system, then you can leave the /i18n/mo directory out of the .gitignore, and commit the files inside.
Now that you have compiled your translations, you can embed them within your application. For this purpose the i18n-embed crate was created.
Add the following to your Cargo.toml dependencies:
toml
[dependencies]
i18n-embed = "VERSION"
A minimal example for how to embed the compiled translations into your application could be:
```rust use i18nembed::{DesktopLanguageRequester, gettext::gettextlanguageloader}; use rustembed::RustEmbed;
struct Translations;
fn main() { let translations = Translations {}; let languageloader = gettextlanguage_loader!();
// Use the language requester for the desktop platform (linux, windows, mac).
// There is also a requester available for the web-sys WASM platform called
// WebLanguageRequester, or you can implement your own.
let requested_languages = DesktopLanguageRequester::requested_languages();
i18n_embed::select(&language_loader, &translations, &requested_languages);
// continue with your application
} ```
You can see the i18n-embed documentation for more detailed examples of how this library can be used.
Now you need to send of the po files to your translators, or provide them access to edit them. Some desktop tools which can be used for the translation include:
Or you could also consider setting up a translation management website for your project to allow translators to edit translations without requiring them to interact with source control or mess around with sending files and installing applications. Some examples:
Self Hosted:
Cloud:
Once you have some updated po files back from translators, or you want to update the po files with new or edited strings, all you need to do is run cargo i18n to update the po files, and recompile updated mo files, then rebuild your application with cargo build.
For some projects using build scripts, with complex pipelines, and with continuous integration, you may want to look into using the i18n-build for automation as an alternative to the cargo i18n command line tool.
For a complete example usage, including localizing sub-crates as libraries, you can see the source code for this project, which localizes itself. This project was originally created to aid in the localization for the coster (work in progress) self-hosted web application.
Available configuration options for i18n.toml:
```toml
fallback_language = "en-US"
i18n.toml then, it will have its localizationsubcrates = ["subcrate1", "subcrate2"]
[gettext]
target_languages = ["es", "ru", "cz"]
i18n.toml of the crateoutput_dir = "i18n"
msgbugsaddress = "example@example.com"
copyright_holder = "You?"
extracttoparent = false
collateextractedsubcrates = false
add_location = "full"
xtr tool.xtr = true
xtr command,msginit and msgmerge commands. Byoutput_dir/pot.pot_dir = "i18n/pot"
msgmerge and msginit commands, and where they will be read from with themsgfmt command. By default this is output_dir/po.po_dir = "i18n/po"
msgfmtoutput_dir/mo.mo_dir = "i18n/mo"
--use-fuzzy option for the msgfmt command. Byuse_fuzzy = false
[fluent]
assets_dir/{language}/{domain}.ftlassets_dir = "i18n" ```
Using the gettext localization system with this tool requires you to have gettext installed on your system.
The msginit, msgfmt, msgmerge and msgcat commands all need to be installed and present in your path.
You also need to ensure that you have the xtr
string extraction command installed, which can be achieved using cargo install
xtr.
Pull-requests are welcome, but for design changes it is preferred that you create a GitHub issue first to discuss it before implementation. You can also contribute to the localization of this tool via:
Or you can also use your favourite po editor directly to help with localizing the files located in i18n/po and i18n-build/i18n/po.
To add a new language, you can make a request via a GitHub issue, or submit a pull request adding the new locale to i18n.toml and generating the associated new po files using cargo i18n.
Translations of this README.md file are also welcome, and can be submitted via pull request. Just name it README.md.lang, where lang is the locale code (see List of ISO 639-1 codes).