Crates.io | i18n-embed |
lib.rs | i18n-embed |
version | 0.14.1 |
source | src |
created_at | 2020-04-07 13:13:56.737804 |
updated_at | 2023-09-27 22:57:45.420261 |
description | Traits and macros to conveniently embed localization assets into your application binary or library in order to localize it at runtime. |
homepage | |
repository | https://github.com/kellpossible/cargo-i18n/tree/master/i18n-embed |
max_upload_size | |
id | 227265 |
size | 112,188 |
Traits and macros to conveniently embed localization assets into your application binary or library in order to localize it at runtime. Works in unison with cargo-i18n.
Currently this library depends on rust-embed to perform the actual embedding of the language files. This may change in the future to make the library more convenient to use.
The i18n-embed
crate has the following optional Cargo features:
fluent-system
FluentLanguageLoader
.gettext-system
GettextLanguageLoader
.desktop-requester
LanguageRequester
trait called DesktopLanguageRequester
for the desktop platform (windows, mac, linux),which makes use of the locale_config crate for resolving the current system locale.web-sys-requester
LanguageRequester
trait called WebLanguageRequester
which makes use of the web-sys crate for resolving the language being requested by the user's web browser in a WASM context.The following is a minimal example for how localize your binary using this library using the fluent localization system.
First you need to compile i18n-embed
in your Cargo.toml
with the fluent-system
and desktop-requester
features enabled:
[dependencies]
i18n-embed = { version = "VERSION", features = ["fluent-system", "desktop-requester"]}
rust-embed = "6"
unic-langid = "0.9"
Set up a minimal i18n.toml
in your crate root to use with cargo-i18n
(see cargo i18n for more information on the configuration file format):
# (Required) The language identifier of the language used in the
# source code for gettext system, and the primary fallback language
# (for which all strings must be present) when using the fluent
# system.
fallback_language = "en-GB"
# Use the fluent localization system.
[fluent]
# (Required) The path to the assets directory.
# The paths inside the assets directory should be structured like so:
# `assets_dir/{language}/{domain}.ftl`
assets_dir = "i18n"
Next, you want to create your localization resources, per language fluent files. language
needs to conform to the Unicode Language Identifier standard, and will be parsed via the unic_langid crate.
The directory structure should look like so:
my_crate/
Cargo.toml
i18n.toml
src/
i18n/
{language}/
{domain}.ftl
Then you can instantiate your language loader and language requester:
use i18n_embed::{DesktopLanguageRequester, fluent::{
FluentLanguageLoader, fluent_language_loader
}};
use rust_embed::RustEmbed;
#[derive(RustEmbed)]
#[folder = "i18n"] // path to the compiled localization resources
struct Localizations;
fn main() {
let language_loader: FluentLanguageLoader = fluent_language_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();
let _result = i18n_embed::select(
&language_loader, &Localizations, &requested_languages);
// continue on with your application
}
To access localizations, you can use FluentLanguageLoader
's methods directly, or, for added compile-time checks/safety, you can use the fl!() macro. Having an i18n.toml
configuration file enables you to do the following:
gettext
localization system.fluent::fluent_language_loader!()
macro to pull the configuration in at compile time to create the fluent::FluentLanguageLoader
.Example projects can be found in examples.
For more explained examples, see the documentation for i18n-embed.