Module i18n 

Internationalization (i18n) module for Pacsea.

This module provides locale detection, resolution, loading, and translation lookup.

Overview

The i18n system supports:

• Locale Detection: Auto-detects system locale from environment variables (LANG, LC_ALL, LC_MESSAGES)
• Locale Resolution: Resolves locale with fallback chain (settings -> system -> default)
• Fallback Chain: Supports locale fallbacks (e.g., de-CH -> de-DE -> en-US)
• Translation Loading: Loads YAML locale files from locales/ directory
• Translation Lookup: Provides t(), t_fmt(), and t_fmt1() helpers for translation access

Locale Files

Locale files are stored in locales/{locale}.yml (e.g., locales/en-US.yml, locales/de-DE.yml). Each file contains a nested YAML structure that is flattened into dot-notation keys:

app:
  titles:
    search: "Search"

This becomes accessible as app.titles.search.

Configuration

The i18n system is configured via config/i18n.yml:

• default_locale: Default locale if auto-detection fails (usually en-US)
• fallbacks: Map of locale codes to their fallback locales

Usage

use pacsea::i18n;
use pacsea::state::AppState;

// Simple translation lookup
let text = i18n::t(&app, "app.titles.search");

// Translation with format arguments
let file_path = "/path/to/file";
let text = i18n::t_fmt1(&app, "app.toasts.exported_to", file_path);

Adding a New Locale

1. Create locales/{locale}.yml (e.g., locales/fr-FR.yml)
2. Copy structure from locales/en-US.yml and translate all strings
3. Optionally add fallback in config/i18n.yml if needed (e.g., fr: fr-FR)
4. Users can set locale = fr-FR in settings.conf or leave empty for auto-detection

Error Handling

• Missing locale files fall back to English automatically
• Invalid locale codes in settings.conf trigger warnings and fallback to system/default
• Missing translation keys return the key itself (for debugging) and log debug messages
• All errors are logged but do not crash the application

Re-exports

pub use translations::TranslationMap;

pub use translations::translate;

pub use translations::translate_with_fallback;

Modules

translations

Translation map and lookup utilities.

Structs

LocaleLoader

Locale loader that caches loaded translations.

LocaleResolver

Locale resolver that caches configuration.

Functions

detect_system_locale

What: Detect system locale from environment variables.

find_config_file

What: Find a config file in development and installed locations.

find_locales_dir

What: Find the locales directory in development and installed locations.

load_locale_file

What: Load a locale YAML file and parse it into a TranslationMap.

resolve_locale

What: Resolve the effective locale to use, following fallback chain.

t

What: Get a translation for a given key from AppState.

t_fmt

What: Get a translation with format arguments.

t_fmt1

What: Get a translation with a single format argument (convenience function).

t_fmt2

What: Format translated string with two format arguments.