locale-match 0.2.4

A small library for selecting the best match for user's preferred locales from available locales.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# locale-match

[![crates.io version](https://img.shields.io/crates/v/locale-match?style=for-the-badge&logo=rust)](https://crates.io/crates/locale-match)
[![docs.rs documentation](https://img.shields.io/docsrs/locale-match/latest?style=for-the-badge&logo=docs.rs&color=2DA44E)](https://docs.rs/locale-match/latest/locale_match)
[![GitHub latest release](https://img.shields.io/github/v/release/pasabanov/locale-match?style=for-the-badge&logo=github&color=8250DF)](https://github.com/pasabanov/locale-match/releases/latest)

A small library for selecting the best match for user's preferred locales from available locales.

The library consists of two modules:
* `bcp47` - for matching locales in the [BCP 47](https://www.ietf.org/rfc/bcp/bcp47.html) format
* `posix` - for matching locales in the [POSIX](https://pubs.opengroup.org/onlinepubs/9799919799/basedefs/V1_chap08.html) format

Both modules provide the `best_matching_locale` function.

### Usage

To use `locale-match` in your project, add it to your `Cargo.toml`:

```toml
# Both modules are included by default
locale-match = "x.y.z"

# Include only the `bcp47` module
locale-match = { version = "x.y.z", default-features = false, features = ["bcp47"] }

# Include only the `posix` module
locale-match = { version = "x.y.z", default-features = false, features = ["posix"] }
```

## Examples

### BCP 47

```rust
use locale_match::bcp47::best_matching_locale;


let available_locales = ["en-US", "en-GB", "ru-UA", "fr-FR", "it"];
let user_locales = ["ru-RU", "ru", "en-US", "en"];

let best_match = best_matching_locale(available_locales, user_locales);

// "ru-UA" is the best match for the highest-priority user locale "ru-RU"
assert_eq!(best_match, Some("ru-UA"));


let available_locales = ["en", "pt-BR", "pt-PT", "es"];
let user_locales = ["pt", "en"];

let best_match = best_matching_locale(available_locales, user_locales);

// "pt-BR" is the first best match for the highest-priority user locale "pt"
assert_eq!(best_match, Some("pt-BR"));


let available_locales = ["zh", "zh-cmn", "zh-cmn-Hans"];
let user_locales = ["zh-Hans"];

let best_match = best_matching_locale(available_locales, user_locales);

// Empty extended language subtag in "zh-Hans" matches any extended language, e.g. "cmn"
assert_eq!(best_match, Some("zh-cmn-Hans"));
```

### POSIX

```rust
use locale_match::posix::best_matching_locale;


let available_locales = ["en_US", "en_GB", "ru_UA", "fr_FR", "it"];
let user_locales = ["ru_RU", "ru", "en_US", "en"];

let best_match = best_matching_locale(available_locales, user_locales);

// "ru_UA" is the best match for the highest-priority user locale "ru_RU"
assert_eq!(best_match, Some("ru_UA"));


let available_locales = ["en", "pt_BR", "pt_PT", "es"];
let user_locales = ["pt", "en"];

let best_match = best_matching_locale(available_locales, user_locales);

// "pt_BR" is the first best match for the highest-priority user locale "pt"
assert_eq!(best_match, Some("pt_BR"));


let available_locales = ["fr", "fr_FR", "fr_CA.UTF-8"];
let user_locales = ["fr.UTF-8"];

let best_match = best_matching_locale(available_locales, user_locales);

// Empty territory in "fr.UTF-8" matches any territory, e.g. "CA"
assert_eq!(best_match, Some("fr_CA.UTF-8"));
```

## License

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

## Copyright

© 2024 Petr Aleksandrovich Sabanov

## Metrics

![repo size](https://img.shields.io/github/repo-size/pasabanov/locale-match?color=8250DF)
![crate size](https://img.shields.io/crates/size/locale-match?label=crate%20size&color=orange)