vendor/fluent-bundle/README.md

   1 # Fluent
   2
   3 `fluent-rs` is a Rust implementation of [Project Fluent][], a localization
   4 framework designed to unleash the entire expressive power of natural language
   5 translations.
   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
  11 Project Fluent keeps simple things simple and makes complex things possible.
  12 The syntax used for describing translations is easy to read and understand.  At
  13 the same time it allows, when necessary, to represent complex concepts from
  14 natural languages like gender, plurals, conjugations, and others.
  15
  16 [Documentation][]
  17
  18 [Project Fluent]: http://projectfluent.org
  19 [Documentation]: https://docs.rs/fluent/
  20
  21 Usage
  22 -----
  23
  24 ```rust
  25 use fluent_bundle::{FluentBundle, FluentResource};
  26 use unic_langid::langid;
  27
  28 fn 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
  51 Status
  52 ------
  53
  54 The implementation is in its early stages and supports only some of the Project
  55 Fluent's spec.  Consult the [list of milestones][] for more information about
  56 release planning and scope.
  57
  58 [list of milestones]: https://github.com/projectfluent/fluent-rs/milestones
  59
  60
  61 Local Development
  62 -----------------
  63
  64     cargo build
  65     cargo test
  66     cargo bench
  67     cargo run --example simple-app
  68
  69 When submitting a PR please use  [`cargo fmt`][] (nightly).
  70
  71 [`cargo fmt`]: https://github.com/rust-lang-nursery/rustfmt
  72
  73
  74 Learn the FTL syntax
  75 --------------------
  76
  77 FTL is a localization file format used for describing translation resources.
  78 FTL stands for _Fluent Translation List_.
  79
  80 FTL is designed to be simple to read, but at the same time allows to represent
  81 complex concepts from natural languages like gender, plurals, conjugations, and
  82 others.
  83
  84     hello-user = Hello, { $username }!
  85
  86 [Read the Fluent Syntax Guide][] in order to learn more about the syntax.  If
  87 you'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
  93 Get Involved
  94 ------------
  95
  96 `fluent-rs` is open-source, licensed under the Apache License, Version 2.0.  We
  97 encourage everyone to take a look at our code and we'll listen to your
  98 feedback.
  99
 100
 101 Discuss
 102 -------
 103
 104 We'd love to hear your thoughts on Project Fluent! Whether you're a localizer
 105 looking for a better way to express yourself in your language, or a developer
 106 trying to make your app localizable and multilingual, or a hacker looking for
 107 a project to contribute to, please do get in touch on the mailing list and the
 108 IRC channel.
 109
 110  - Discourse: https://discourse.mozilla.org/c/fluent
 111  - IRC channel: [irc://irc.mozilla.org/l20n](irc://irc.mozilla.org/l20n)