sys_language 0.1.0

# sys_language


A cross-platform Rust library for detecting the system's default language with support for preferred language selection and fallback mechanisms.

## Authors


- [Cupnfish](https://github.com/cupnfish)
- z.ai

## Features


- 🌍 **Cross-platform Support**: Works on Windows, macOS, and Linux
- 🎯 **Smart Matching**: Supports exact matching and primary language matching
- ⚡ **Flexible Configuration**: Supports preferred language lists and fallback language settings
- 🔧 **Easy to Use**: Provides simple API and convenience functions

## Installation


Add the dependency to your `Cargo.toml`:

```toml
[dependencies]
sys_language = "0.1.0"
```

## Usage


### Basic Usage


```rust
use sys_language::detect_system_language;

let language = detect_system_language();
println!("System language: {}", language);
println!("Primary language: {}", language.primary_language());
```

### Advanced Usage


```rust
use sys_language::LanguageDetector;

let detector = LanguageDetector::new()
    .with_preferred_languages(&["zh-CN", "en-US", "ja-JP"])
    .with_fallback("en-US");

let language = detector.detect();
println!("Detected language: {}", language);
```

### Using Convenience Functions


```rust
use sys_language::detect_language_with_options;

let preferred = ["zh-CN", "en-US"];
let fallback = "en-US";
let language = detect_language_with_options(&preferred, fallback);
println!("Best language: {}", language);
```

## Language Matching Rules


The library supports intelligent language matching, including:

1. **Exact Matching**: `zh-CN` exactly matches `zh-CN`
2. **Primary Language Matching**: `zh-CN` matches `zh`
3. **Same Primary Language**: `zh-CN` matches `zh-TW`

```rust
use sys_language::Language;

let lang = Language::new("zh-CN");

assert!(lang.matches("zh-CN"));  // Exact match
assert!(lang.matches("zh"));     // Primary language match
assert!(lang.matches("zh-TW"));  // Same primary language
assert!(!lang.matches("en-US")); // No match
```

## Platform-Specific Implementations


### Windows


Uses Windows API (`GetUserDefaultLocaleName`) to get system language settings.

### macOS


Reads language settings from environment variables (`LANG`, `LC_ALL`, `LC_CTYPE`).

### Linux


Reads language settings from environment variables (`LANG`, `LC_ALL`, `LANGUAGE`), with support for colon-separated language lists.

## Example Program


Run the example program to see all features in action:

```bash
cargo run --example basic_usage
```

Example output:

```
=== System Language Detection Example ===

1. Detect system default language:
   System language: zh-CN
   Primary language: zh
   Region: CN

2. Using LanguageDetector:
   Detected language: zh-CN
   Preferred languages: ["zh-CN", "zh-TW", "en-US"]
   Fallback language: en-US

3. Test language matching logic:
   Case 1 (preferred: zh-CN, en-US): zh-CN
   Case 2 (preferred: zh-CN, ja-JP): zh-CN
   Case 3 (no preferred languages): fr-FR

4. Using convenience functions:
   Preferred: ["de-DE", "fr-FR", "es-ES"], Fallback: en-US
   Result: de-DE

5. Language matching rules demonstration:
   'zh-CN' matches 'zh-CN'? true
   'zh-CN' matches 'zh'? true
   'zh-CN' matches 'zh-TW'? true
   'zh-CN' matches 'en-US'? false

=== Example End ===
```

## API Documentation


### Language Struct


```rust
pub struct Language {
    code: String,
}
```

**Methods:**

- `new(code: &str) -> Language` - Create a new language instance
- `as_str(&self) -> &str` - Get the language code as a string
- `primary_language(&self) -> &str` - Get the primary language part
- `region(&self) -> Option<&str>` - Get the region part
- `matches(&self, other: &str) -> bool` - Check if it matches the specified language

### LanguageDetector Struct


```rust
pub struct LanguageDetector {
    preferred_languages: Vec<String>,
    fallback: String,
}
```

**Methods:**

- `new() -> Self` - Create a new language detector
- `with_preferred_languages(self, languages: &[&str]) -> Self` - Set preferred language list
- `with_fallback(self, fallback: &str) -> Self` - Set fallback language
- `preferred_languages(&self) -> &[String]` - Get preferred language list
- `fallback(&self) -> &str` - Get fallback language
- `detect(&self) -> Language` - Detect and return the best language

### Convenience Functions


- `detect_system_language() -> Language` - Quick system language detection
- `detect_language_with_options(preferred: &[&str], fallback: &str) -> Language` - Detect language with options

## License


MIT License

## Contributing


Issues and Pull Requests are welcome!

## Changelog


### v0.1.0

- Initial release
- Support for Windows, macOS, and Linux platforms
- Basic language detection and matching functionality
- Flexible configuration options