Metadata-Version: 2.4
Name: fluent-manager
Version: 1.0.1
Summary: Lightweight Fluent localisation manager with automatic locale fallback
Author-email: Andrii Bogdanovych <a@bogdanovych.org>
License: MIT
Project-URL: Homepage, https://www.bogdanovych.org
Project-URL: Repository, https://github.com/BogdanovychA/fluent-manager
Project-URL: DOI, https://doi.org/10.5281/zenodo.19492979
Project-URL: Bug Tracker, https://github.com/BogdanovychA/fluent-manager/issues
Project-URL: PyPI Stats, https://pypistats.org/packages/fluent-manager
Keywords: fluent,localization,i18n,l10n,python,translation
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fluent-runtime>=0.4.0
Dynamic: license-file

# fluent-manager

[![DOI](https://zenodo.org/badge/1186346418.svg)](https://doi.org/10.5281/zenodo.19492979) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/fluent-manager?period=total&units=INTERNATIONAL_SYSTEM&left_color=GREY&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/fluent-manager)

Translations: [🇺🇦 Українська](https://github.com/BogdanovychA/fluent-manager/blob/main/README.uk.md) · [🇵🇱 Polski](https://github.com/BogdanovychA/fluent-manager/blob/main/README.pl.md)

Lightweight [Project Fluent](https://projectfluent.org/) localisation manager with automatic locale fallback.

## Installation

```bash
pip install fluent-manager
```

## Features

- Simple API for retrieving localised strings
- Automatic fallback chain: preferred locales → default locale → key itself
- Auto-discovery of available locales and `.ftl` resource files from the filesystem
- Supports multiple preferred locales in priority order

## Directory structure

```
locales/
├── en/
│   └── messages.ftl
├── uk/
│   └── messages.ftl
└── pl/
    └── messages.ftl
```

## Usage

```python
from fluent_manager import FluentManager

lang_manager = FluentManager(
    locales=["uk", "pl"],
    locales_path="/path/to/locales",
    default_locale="en",
)

# Returns localised string in the first matching locale
message = lang_manager.get("welcome-message", user_name="Andrii")
```

## Fallback behaviour

| Situation | Result |
|---|---|
| Key exists in first preferred locale | Renders in first preferred locale |
| Key missing in first locale, exists in next | Renders in next preferred locale |
| Key exists only in default locale | Renders in default locale |
| Key missing in all locales | Returns the key itself |

## API

### `FluentManager(locales, locales_path, default_locale=None)`

| Parameter | Type | Description |
|---|---|---|
| `locales` | `list` | Preferred locales in priority order, e.g. `["uk", "pl"]` |
| `locales_path` | `str` | Path to the directory containing locale subdirectories |
| `default_locale` | `str \| None` | Fallback locale. Defaults to `"en"` |

### `FluentManager.get(key, **kwargs) -> str`

Retrieves a localised string by key with optional variables.

### `FluentManager.languages -> list`

List of all available locales detected from the filesystem.

## Links

- [Project Fluent](https://projectfluent.org/)
- [Repository](https://github.com/BogdanovychA/fluent-manager)
