third_party/rust/fluent-fallback/README.md

   1 # Fluent
   2
   3 `fluent-fallback` is a Rust implementation of the [Project Fluent][] higher level API.
   4
   5 The `Localization` struct encapsulates a persistant localization context providing
   6 language fallbacking. The instance remains available throughout the whole life cycle of
   7 the corresponding UI, reacting to events such as locale changes, resource updates etc.
   8
   9 The API can be used directly, or can serve as an example of state manager for `fluent-bundle` and `fluent-resmgr`.
  10
  11 [![crates.io](https://img.shields.io/crates/v/fluent-fallback.svg)](https://crates.io/crates/fluent-fallback)
  12 [![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)
  13 [![Coverage Status](https://coveralls.io/repos/github/projectfluent/fluent-rs/badge.svg?branch=master)](https://coveralls.io/github/projectfluent/fluent-rs?branch=master)
  14
  15 Project Fluent keeps simple things simple and makes complex things possible.
  16 The syntax used for describing translations is easy to read and understand.  At
  17 the same time it allows, when necessary, to represent complex concepts from
  18 natural languages like gender, plurals, conjugations, and others.
  19
  20 [Documentation][]
  21
  22 [Project Fluent]: http://projectfluent.org
  23 [Documentation]: https://docs.rs/fluent/
  24
  25 Usage
  26 -----
  27
  28 ```rust
  29 use fluent_fallback::Localization;
  30
  31 fn main() {
  32     // generate_messages is a closure that returns an iterator over FluentBundle
  33     // instances.
  34     let loc = Localization::new(vec!["simple.ftl".into()], generate_messages);
  35
  36     let value = bundle.format_value("hello-world", None);
  37
  38     assert_eq!(&value, "Hello, world!");
  39 }
  40 ```
  41
  42
  43 Status
  44 ------
  45
  46 The implementation is in its early stages and supports only some of the Project
  47 Fluent's spec.  Consult the [list of milestones][] for more information about
  48 release planning and scope.
  49
  50 [list of milestones]: https://github.com/projectfluent/fluent-rs/milestones
  51
  52
  53 Local Development
  54 -----------------
  55
  56     cargo build
  57     cargo test
  58     cargo run --example simple-fallback
  59
  60 When submitting a PR please use  [`cargo fmt`][] (nightly).
  61
  62 [`cargo fmt`]: https://github.com/rust-lang-nursery/rustfmt
  63
  64
  65 Learn the FTL syntax
  66 --------------------
  67
  68 FTL is a localization file format used for describing translation resources.
  69 FTL stands for _Fluent Translation List_.
  70
  71 FTL is designed to be simple to read, but at the same time allows to represent
  72 complex concepts from natural languages like gender, plurals, conjugations, and
  73 others.
  74
  75     hello-user = Hello, { $username }!
  76
  77 [Read the Fluent Syntax Guide][] in order to learn more about the syntax.  If
  78 you're a tool author you may be interested in the formal [EBNF grammar][].
  79
  80 [Read the Fluent Syntax Guide]: http://projectfluent.org/fluent/guide/
  81 [EBNF grammar]: https://github.com/projectfluent/fluent/tree/master/spec
  82
  83
  84 Get Involved
  85 ------------
  86
  87 `fluent-rs` is open-source, licensed under the Apache License, Version 2.0.  We
  88 encourage everyone to take a look at our code and we'll listen to your
  89 feedback.
  90
  91
  92 Discuss
  93 -------
  94
  95 We'd love to hear your thoughts on Project Fluent! Whether you're a localizer
  96 looking for a better way to express yourself in your language, or a developer
  97 trying to make your app localizable and multilingual, or a hacker looking for
  98 a project to contribute to, please do get in touch on the mailing list and the
  99 IRC channel.
 100
 101  - Discourse: https://discourse.mozilla.org/c/fluent
 102  - IRC channel: [irc://irc.mozilla.org/l20n](irc://irc.mozilla.org/l20n)