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](http://meritbadge.herokuapp.com/fluent)](https://crates.io/crates/fluent) 8[![Build Status](https://travis-ci.org/projectfluent/fluent-rs.svg?branch=master)](https://travis-ci.org/projectfluent/fluent-rs) 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::{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("Failed to parse an FTL string."); 32 33 let langid_en = langid!("en-US"); 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("Message doesn't exist."); 41 let mut errors = vec![]; 42 let pattern = msg.value 43 .expect("Message has no value."); 44 let value = bundle.format_pattern(&pattern, None, &mut errors); 45 46 assert_eq!(&value, "Hello, world!"); 47} 48``` 49 50 51Status 52------ 53 54The implementation is in pre-1.0 mode and supports Fluent Syntax 1.0, and 55Fluent API 0.14.. Consult the [list of milestones][] for more information about 56release planning and scope. 57 58`FluentBundle`, which is the main struct at the moment, is intended to remain 59a low level API. 60There is a number of higher level APIs like [fluent-resmgr][] and 61[fluent-fallback][] intended to wrap around it and provide better ergonomics 62for bindings and direct usage. 63Those higher level APIs are not mature yet enough to be included in this package, 64but will get added once they are. 65 66[list of milestones]: https://github.com/projectfluent/fluent-rs/milestones 67[fluent-resmgr]: https://crates.io/crates/fluent-resmgr 68[fluent-fallback]: https://crates.io/crates/fluent-fallback 69 70Local Development 71----------------- 72 73 cargo build 74 cargo test 75 cargo bench 76 cargo run --example simple-app 77 78When submitting a PR please use [`cargo fmt`][] (nightly). 79 80[`cargo fmt`]: https://github.com/rust-lang-nursery/rustfmt 81 82 83Learn the FTL syntax 84-------------------- 85 86FTL is a localization file format used for describing translation resources. 87FTL stands for _Fluent Translation List_. 88 89FTL is designed to be simple to read, but at the same time allows to represent 90complex concepts from natural languages like gender, plurals, conjugations, and 91others. 92 93 hello-user = Hello, { $username }! 94 95[Read the Fluent Syntax Guide][] in order to learn more about the syntax. If 96you're a tool author you may be interested in the formal [EBNF grammar][]. 97 98[Read the Fluent Syntax Guide]: http://projectfluent.org/fluent/guide/ 99[EBNF grammar]: https://github.com/projectfluent/fluent/tree/master/spec 100 101 102Get Involved 103------------ 104 105`fluent-rs` is open-source, licensed under the Apache License, Version 2.0. We 106encourage everyone to take a look at our code and we'll listen to your 107feedback. 108 109 110Discuss 111------- 112 113We'd love to hear your thoughts on Project Fluent! Whether you're a localizer 114looking for a better way to express yourself in your language, or a developer 115trying to make your app localizable and multilingual, or a hacker looking for 116a project to contribute to, please do get in touch on the mailing list and the 117IRC channel. 118 119 - Discourse: https://discourse.mozilla.org/c/fluent 120 - IRC channel: [irc://irc.mozilla.org/l20n](irc://irc.mozilla.org/l20n) 121