4 releases

✓ Uses Rust 2018 edition

new 0.4.8 May 30, 2020
0.4.7 May 22, 2020
0.4.6 Apr 26, 2020
0.4.5 Apr 26, 2020

#15 in Internationalization (i18n)

23 downloads per month

MIT/Apache

38KB
632 lines

fluent-templates: A high level Fluent & Fluent Template API.

CI Status Current Version License: MIT/Apache-2.0

fluent-templates provides a high level API for adding fluent to your Rust project, and provides optional integrations with templating languages.

Loaders

The "loader" APIs read a directory and will load all fluent resources in each subdirectory that is a valid [Unicode Language Identifier]. You can also specify shared fluent resources that are used across all localisations.

  • [StaticLoader] — Created with the static_loader! macro, StaticLoader will load the localisations into static memory. This most useful when the location of your fluent localisations is known at compile-time.
  • [ArcLoader] — A struct that uses atomic references to store the localisations. Useful for when the source of your localisations are only known at run-time.

Example Layout

locales
├── core.ftl
├── en-US
│   └── main.ftl
├── fr
│   └── main.ftl
├── zh-CN
│   └── main.ftl
└── zh-TW
    └── main.ftl

Example

The easiest way to use fluent-templates is to use the static_loader! macro:

fluent_templates::static_loader!(create_loader, "./locales/", "en-US");

fn main() {
    let loader = create_loader();

    assert_eq!("Hello World!", loader.lookup_single_language(&unic_langid::langid!("en-US"), "welcome-text", None).unwrap());
}

Tera

# #[cfg(feature = "handlebars")] {
use tera::Tera;

fluent_templates::static_loader!(create_loader, "./locales/", "en-US");

fn init(tera: &mut Tera) {
    let loader = create_loader();
    let helper = fluent_templates::FluentHelper::new(loader);
    tera.register_function("fluent", helper);
}

fn render_page(tera: &mut Tera, ctx: &tera::Context) -> String {
    tera.render_str(r#"{{ fluent(key="foo-bar", lang="en") }} baz"#, ctx).unwrap()
}
# }

Handlebars

# #[cfg(feature = "handlebars")] {
use handlebars::Handlebars;

fluent_templates::static_loader!(create_loader, "./locales/", "en-US");

fn init(handlebars: &mut Handlebars) {
    let loader = create_loader();
    let helper = fluent_templates::FluentHelper::new(loader);
    handlebars.register_helper("fluent", Box::new(helper));
}

fn render_page(handlebars: &Handlebars) -> String {
    let data = serde_json::json!({"lang": "zh-CN"});
    handlebars.render_template("{{fluent \"foo-bar\"}} baz", &data).unwrap()
}
# }

You should have a locales/ folder somewhere with one folder per language code, containing all of your FTL files. See the static_loader! macro for more options.

Make sure the [handlebars::Context] has a top-level "lang" field when rendering.

Handlebars helper syntax.

The main helper provided is the {{fluent}} helper. If you have the following Fluent file:

foo-bar = "foo bar"
placeholder = this has a placeholder { $variable }

You can include the strings in your template with

{{fluent "foo-bar"}} <!-- will render "foo bar" -->
{{fluent "placeholder" variable="baz"}} <!-- will render "this has a placeholder baz" -->
``

You may also use the `{{fluentparam}}` helper to specify [variables], especially if you need
them to be multiline, like so:

```hbs
{{#fluent "placeholder"}}
    {{#fluentparam "variable"}}
        first line
        second line
    {{/fluentparam}}
{{/fluent}}

Multiple {{fluentparam}}s may be specified

Features/Template Engines

Basic handlebars example

//! Requires `--features handlebars`.
use fluent_templates::*;
use handlebars::*;
use serde_json::*;

static_loader!(create_loader, "./locales/", "en-US");

fn init(handlebars: &mut Handlebars) {
    let loader = create_loader();
    let helper = FluentHelper::new(loader);
    handlebars.register_helper("fluent", Box::new(helper));
}

fn render_page(handlebars: &Handlebars) -> String {
    let data = json!({"lang": "zh-CN"});
    handlebars.render_template("{{fluent \"foo-bar\"}} baz", &data).unwrap()
}

Dependencies

~2–3.5MB
~71K SLoC