fluent_template_helper/lib.rs
1//! [Fluent](https://projectfluent.org/) helper for [Handlebars](https://docs.rs/handlebars).
2//!
3//! This crate provides a Handlebars helper that can load Fluent strings.
4//!
5//!
6//! # Setting up the fluent helper with handlebars
7//!
8//! The easiest way to use this is to use the [`simple_loader!()`] macro:
9//!
10//! ```rust
11//! use fluent_template_helper::*;
12//! use handlebars::*;
13//! use serde_json::*;
14//!
15//! static_loader!(create_loader, "./locales/", "en-US");
16//!
17//! fn init(handlebars: &mut Handlebars) {
18//! let loader = create_loader();
19//! let helper = FluentHelper::new(loader);
20//! handlebars.register_helper("fluent", Box::new(helper));
21//! }
22//!
23//! fn render_page(handlebars: &Handlebars) -> String {
24//! let data = json!({"lang": "zh-CN"});
25//! handlebars.render_template("{{fluent \"foo-bar\"}} baz", &data).unwrap()
26//! }
27//! ```
28//!
29//! You should have a `locales/` folder somewhere with one folder per language code,
30//! containing all of your FTL files. See the [`simple_loader!()`] macro for more options.
31//!
32//! Make sure the [`handlebars::Context`] has a toplevel "lang" field when rendering.
33//!
34//!
35//! # Using the fluent helper in your templates
36//!
37//! The main helper provided is the `{{fluent}}` helper. If you have the following Fluent
38//! file:
39//!
40//! ```fluent
41//! foo-bar = "foo bar"
42//! placeholder = this has a placeholder { $variable }
43//! ```
44//!
45//! You can include the strings in your template with
46//!
47//! ```hbs
48//! {{fluent "foo-bar"}} <!-- will render "foo bar" -->
49//! {{fluent "placeholder" variable="baz"}} <!-- will render "this has a placeholder baz" -->
50//!```
51//!
52//! You may also use the `{{fluentparam}}` helper to specify [variables], especially if you need
53//! them to be multiline, like so:
54//!
55//! ```hbs
56//! {{#fluent "placeholder"}}
57//! {{#fluentparam "variable"}}
58//! first line
59//! second line
60//! {{/fluentparam}}
61//! {{/fluent}}
62//! ```
63//!
64//! Multiple `{{fluentparam}}`s may be specified
65//!
66//! [variables]: https://projectfluent.org/fluent/guide/variables.html
67//! [`simple_loader!()`]: ./macro.simple_loader.html
68
69#[doc(hidden)]
70pub extern crate lazy_static;
71
72#[doc(hidden)]
73pub extern crate fluent_bundle;
74
75pub use helper::FluentHelper;
76pub use loader::{ArcLoader, ArcLoaderBuilder, Loader, StaticLoader};
77
78mod helper;
79pub mod loader;