113 lines
4.3 KiB
Markdown
113 lines
4.3 KiB
Markdown
# 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
|
|
|