diff options
Diffstat (limited to 'third_party/rust/fluent-langneg/README.md')
| -rw-r--r-- | third_party/rust/fluent-langneg/README.md | 113 |
1 files changed, 113 insertions, 0 deletions
diff --git a/third_party/rust/fluent-langneg/README.md b/third_party/rust/fluent-langneg/README.md new file mode 100644 index 0000000000..bdff7649f8 --- /dev/null +++ b/third_party/rust/fluent-langneg/README.md @@ -0,0 +1,113 @@ +# Fluent LangNeg + +**Fluent LangNeg is a library for language and locale identifier negotiation.** + +[](https://crates.io/crates/fluent-langneg) +[](https://travis-ci.org/projectfluent/fluent-langneg-rs) +[](https://coveralls.io/github/projectfluent/fluent-langneg-rs?branch=master) + +Introduction +------------ + +This is a Rust implementation of fluent-langneg library which is a part of Project Fluent. + +The library uses [unic-langid](https://github.com/zbraniecki/unic-locale) and [unic-locale](https://github.com/zbraniecki/unic-locale) to retrieve and operate on Unicode Language and Locale Identifiers. +The library provides algorithm for negotiating between lists of locales. + +Usage +----- + +```rust +use fluent_langneg::negotiate_languages; +use fluent_langneg::NegotiationStrategy; +use fluent_langneg::convert_vec_str_to_langids_lossy; +use unic_langid::LanguageIdentifier + +// Since langid parsing from string is fallible, we'll use a helper +// function which strips any langids that failed to parse. +let requested = convert_vec_str_to_langids_lossy(&["de-DE", "fr-FR", "en-US"]); +let available = convert_vec_str_to_langids_lossy(&["it", "fr", "de-AT", "fr-CA", "en-US"]); +let default: LanguageIdentifier = "en-US".parse().expect("Parsing langid failed."); + +let supported = negotiate_languages( + &requested, + &available, + Some(&default), + NegotiationStrategy::Filtering +); + +let expected = convert_vec_str_to_langids_lossy(&["de-AT", "fr", "fr-CA", "en-US"]); +assert_eq!(supported, + expected.iter().map(|t| t.as_ref()).collect::<Vec<&LanguageIdentifier>>()); +``` + +See [docs.rs][] for more examples. + +[docs.rs]: https://docs.rs/fluent-langneg/ + +Status +------ + +The implementation is complete according to fluent-langneg +corpus of tests, which means that it parses, serializes and negotiates as expected. + +The negotiation methods can operate on lists of `LanguageIdentifier` or `Locale`. + +The remaining work is on the path to 1.0 is to gain in-field experience of using it, +add more tests and ensure that bad input is correctly handled. + +Compatibility +------------- + +The API is based on [UTS 35][] definition of [Unicode Locale Identifier][] and is aiming to +parse and serialize all locale identifiers according to that definition. + +*Note*: Unicode Locale Identifier is similar, but different, from what [BCP47][] specifies under +the name Language Tag. +For most locale management and negotiation needs, the Unicode Locale Identifier used in this crate is likely a better choice, +but in some case, like HTTP Accepted Headers, you may need the complete BCP47 Language Tag implementation which +this crate does not provide. + +Language negotiation algorithms are custom Project Fluent solutions, +based on [RFC4647][]. + +The language negotiation strategies aim to replicate the best-effort matches with +the most limited amount of data. The algorithm returns reasonable +results without any database, but the results can be improved with either limited +or full [CLDR likely-subtags][] database. + +The result is a balance chosen for Project Fluent and may differ from other +implementations of language negotiation algorithms which may choose different +tradeoffs. + +[BCP47]: https://tools.ietf.org/html/bcp47 +[RFC6067]: https://www.ietf.org/rfc/rfc6067.txt +[UTS 35]: http://www.unicode.org/reports/tr35/#Locale_Extension_Key_and_Type_Data +[RFC4647]: https://tools.ietf.org/html/rfc4647 +[CLDR likely-subtags]: http://www.unicode.org/cldr/charts/latest/supplemental/likely_subtags.html +[Unicode Locale Identifier]: (http://unicode.org/reports/tr35/#Identifiers) + +Alternatives +------------ + +Although Fluent Locale aims to stay close to W3C Accepted Languages, it does not aim +to implement the full behavior and some aspects of the language negotiation strategy +recommended by W3C, such as weights, are not a target right now. + +For such purposes, [rust-language-tags][] crate seems to be a better choice. + +[rust-language-tags]: https://github.com/pyfisch/rust-language-tags + +Performance +----------- + +The crate is considered to be fully optimized for production. + + +Develop +------- + + cargo build + cargo test + cargo bench + |