[][src]Crate fluent_templates

Fluent Templates: Templating for Fluent

This crate provides "loaders" that are able to load fluent strings based on simple language negotiation, and the FluentHelper which is an opague type that provides the integration between a given templating engine such as handlebars or tera.

Loaders

Currently this crate provides two different kinds of loaders that cover two main use cases.

  • static_loader! — A macro that generates a loader that loads the localisations into static memory. Useful for when your localisations are known at compile-time.
  • ArcLoader — A struct that atomically stores and reference counts the localisations. Useful for when your localisations are only known at run-time.

Example

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

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

Tera

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

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:

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

Multiple {{fluentparam}}s may be specified

Re-exports

pub use loader::Loader;

Modules

loader

This modules contains both the static_loader and ArcLoader implementations, as well as the Loader trait. Which provides a loader agnostic interface.

Macros

static_loader

Loads Fluent data at runtime via lazy_static to produce a loader.

Structs

ArcLoader

A loader that uses Arc<FluentResource> as its backing storage. This is mainly useful for when you need to load fluent at run time. You can configure the initialisation with ArcLoaderBuilder.

ArcLoaderBuilder

A builder pattern struct for constructing ArcLoaders.

FluentHelper

A concrete type that provides a loader agnostic implementation

StaticLoader

A simple Loader implementation, with statically-loaded fluent data. Typically created with the [static_loader!()] macro

Enums

LoaderError

Errors that can occur when loading or parsing fluent resources.

Type Definitions

Result

A convenience Result type that defaults to error::Loader.