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
• 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:

[dependencies]
sys_language = "0.1.0"

Usage

Basic Usage

use sys_language::detect_system_language;

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

Advanced Usage

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

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

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:

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

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

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