1# Fluent
2
3`fluent-rs` is a Rust implementation of [Project Fluent][], a localization
4framework designed to unleash the entire expressive power of natural language
5translations.
6
7[![crates.io](https://img.shields.io/crates/v/fluent-bundle.svg)](https://crates.io/crates/fluent-bundle)
8[![Build and test](https://github.com/projectfluent/fluent-rs/workflows/Build%20and%20test/badge.svg)](https://github.com/projectfluent/fluent-rs/actions?query=branch%3Amaster+workflow%3A%22Build+and+test%22)
9[![Coverage Status](https://coveralls.io/repos/github/projectfluent/fluent-rs/badge.svg?branch=master)](https://coveralls.io/github/projectfluent/fluent-rs?branch=master)
10
11Project Fluent keeps simple things simple and makes complex things possible.
12The syntax used for describing translations is easy to read and understand.  At
13the same time it allows, when necessary, to represent complex concepts from
14natural languages like gender, plurals, conjugations, and others.
15
16[Documentation][]
17
18[Project Fluent]: http://projectfluent.org
19[Documentation]: https://docs.rs/fluent/
20
21Usage
22-----
23
24```rust
25use fluent_bundle::{FluentBundle, FluentResource};
26use unic_langid::langid;
27
28fn main() {
29    let ftl_string = "hello-world = Hello, world!".to_owned();
30    let res = FluentResource::try_new(ftl_string)
31        .expect("Could not parse an FTL string.");
32
33    let langid_en = langid!("en");
34    let mut bundle = FluentBundle::new(vec![langid_en]);
35
36    bundle.add_resource(&res)
37        .expect("Failed to add FTL resources to the bundle.");
38
39    let msg = bundle.get_message("hello-world")
40        .expect("Failed to retrieve a message.");
41    let val = msg.value.expect("Message has no value.");
42
43    let mut errors = vec![];
44    let value = bundle.format_pattern(val, None, &mut errors);
45
46    assert_eq!(&value, "Hello, world!");
47}
48```
49
50
51Status
52------
53
54The implementation is in its early stages and supports only some of the Project
55Fluent's spec.  Consult the [list of milestones][] for more information about
56release planning and scope.
57
58[list of milestones]: https://github.com/projectfluent/fluent-rs/milestones
59
60
61Local Development
62-----------------
63
64    cargo build
65    cargo test
66    cargo bench
67    cargo run --example simple-app
68
69When submitting a PR please use  [`cargo fmt`][] (nightly).
70
71[`cargo fmt`]: https://github.com/rust-lang-nursery/rustfmt
72
73
74Learn the FTL syntax
75--------------------
76
77FTL is a localization file format used for describing translation resources.
78FTL stands for _Fluent Translation List_.
79
80FTL is designed to be simple to read, but at the same time allows to represent
81complex concepts from natural languages like gender, plurals, conjugations, and
82others.
83
84    hello-user = Hello, { $username }!
85
86[Read the Fluent Syntax Guide][] in order to learn more about the syntax.  If
87you're a tool author you may be interested in the formal [EBNF grammar][].
88
89[Read the Fluent Syntax Guide]: http://projectfluent.org/fluent/guide/
90[EBNF grammar]: https://github.com/projectfluent/fluent/tree/master/spec
91
92
93Get Involved
94------------
95
96`fluent-rs` is open-source, licensed under the Apache License, Version 2.0.  We
97encourage everyone to take a look at our code and we'll listen to your
98feedback.
99
100
101Discuss
102-------
103
104We'd love to hear your thoughts on Project Fluent! Whether you're a localizer
105looking for a better way to express yourself in your language, or a developer
106trying to make your app localizable and multilingual, or a hacker looking for
107a project to contribute to, please do get in touch on the mailing list and the
108IRC channel.
109
110 - Discourse: https://discourse.mozilla.org/c/fluent
111 - IRC channel: [irc://irc.mozilla.org/l20n](irc://irc.mozilla.org/l20n)
112