README.md
1# Fluent LangNeg
2
3**Fluent LangNeg is a library for language and locale identifier negotiation.**
4
5[](https://crates.io/crates/fluent-langneg)
6[](https://travis-ci.org/projectfluent/fluent-langneg-rs)
7[](https://coveralls.io/github/projectfluent/fluent-langneg-rs?branch=master)
8
9Introduction
10------------
11
12This is a Rust implementation of fluent-langneg library which is a part of Project Fluent.
13
14The 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.
15The library provides algorithm for negotiating between lists of locales.
16
17Usage
18-----
19
20```rust
21use fluent_langneg::negotiate_languages;
22use fluent_langneg::NegotiationStrategy;
23use fluent_langneg::convert_vec_str_to_langids_lossy;
24use unic_langid::LanguageIdentifier
25
26// Since langid parsing from string is fallible, we'll use a helper
27// function which strips any langids that failed to parse.
28let requested = convert_vec_str_to_langids_lossy(&["de-DE", "fr-FR", "en-US"]);
29let available = convert_vec_str_to_langids_lossy(&["it", "fr", "de-AT", "fr-CA", "en-US"]);
30let default: LanguageIdentifier = "en-US".parse().expect("Parsing langid failed.");
31
32let supported = negotiate_languages(
33 &requested,
34 &available,
35 Some(&default),
36 NegotiationStrategy::Filtering
37);
38
39let expected = convert_vec_str_to_langids_lossy(&["de-AT", "fr", "fr-CA", "en-US"]);
40assert_eq!(supported,
41 expected.iter().map(|t| t.as_ref()).collect::<Vec<&LanguageIdentifier>>());
42```
43
44See [docs.rs][] for more examples.
45
46[docs.rs]: https://docs.rs/fluent-langneg/
47
48Status
49------
50
51The implementation is complete according to fluent-langneg
52corpus of tests, which means that it parses, serializes and negotiates as expected.
53
54The negotiation methods can operate on lists of `LanguageIdentifier` or `Locale`.
55
56The remaining work is on the path to 1.0 is to gain in-field experience of using it,
57add more tests and ensure that bad input is correctly handled.
58
59Compatibility
60-------------
61
62The API is based on [UTS 35][] definition of [Unicode Locale Identifier][] and is aiming to
63parse and serialize all locale identifiers according to that definition.
64
65*Note*: Unicode Locale Identifier is similar, but different, from what [BCP47][] specifies under
66the name Language Tag.
67For most locale management and negotiation needs, the Unicode Locale Identifier used in this crate is likely a better choice,
68but in some case, like HTTP Accepted Headers, you may need the complete BCP47 Language Tag implementation which
69this crate does not provide.
70
71Language negotiation algorithms are custom Project Fluent solutions,
72based on [RFC4647][].
73
74The language negotiation strategies aim to replicate the best-effort matches with
75the most limited amount of data. The algorithm returns reasonable
76results without any database, but the results can be improved with either limited
77or full [CLDR likely-subtags][] database.
78
79The result is a balance chosen for Project Fluent and may differ from other
80implementations of language negotiation algorithms which may choose different
81tradeoffs.
82
83[BCP47]: https://tools.ietf.org/html/bcp47
84[RFC6067]: https://www.ietf.org/rfc/rfc6067.txt
85[UTS 35]: http://www.unicode.org/reports/tr35/#Locale_Extension_Key_and_Type_Data
86[RFC4647]: https://tools.ietf.org/html/rfc4647
87[CLDR likely-subtags]: http://www.unicode.org/cldr/charts/latest/supplemental/likely_subtags.html
88[Unicode Locale Identifier]: (http://unicode.org/reports/tr35/#Identifiers)
89
90Alternatives
91------------
92
93Although Fluent Locale aims to stay close to W3C Accepted Languages, it does not aim
94to implement the full behavior and some aspects of the language negotiation strategy
95recommended by W3C, such as weights, are not a target right now.
96
97For such purposes, [rust-language-tags][] crate seems to be a better choice.
98
99[rust-language-tags]: https://github.com/pyfisch/rust-language-tags
100
101Performance
102-----------
103
104The crate is considered to be fully optimized for production.
105
106
107Develop
108-------
109
110 cargo build
111 cargo test
112 cargo bench
113
114
){kind=link}
){kind=link}