doti18n 0.3.3

Python library for loading localizations with dot access and pluralization.

doti18n

Simple and intuitive Python library for loading localizations from YAML, JSON, XML files and accessing them easily using dot notation, with powerful support for plural forms and nested data structures.

Description

doti18n provides a convenient way to manage your application's localization strings. By loading data from files, the library allows you to access nested translations using a simple dot syntax (messages.status.online) for dictionary keys and index syntax (items[0]) for list elements. You can combine these for intuitive navigation through complex nested structures (pages[0].title).

Special attention is given to pluralization support using the Babel library, which is critical for correct localization across different languages. An automatic fallback mechanism to the default locale's value is also implemented if a key or path is missing in the requested locale.

The library offers both a forgiving non-strict mode (returning a special wrapper and logging warnings) and a strict mode (raising exceptions) for handling missing paths.

It's designed for ease of use and performance (data is loaded once during initialization and translator objects are cached).

Features

• Loading localization data from YAML, JSON, XML files.
• Intuitive access to nested data structures (dictionaries and lists) using dot notation (.) for dictionary keys and index notation ([]) for list elements.
• Support for combined access paths (data.list[0].nested_key).
• Strict mode (strict=True) to raise exceptions on missing paths or incorrect usage.
• Non-strict mode (default) to return a special NoneWrapper object and log a warning on missing paths or incorrect usage.
• Pluralization support for count-dependent strings (requires Babel).
• Automatic fallback to the default locale if a key/path is missing in the current locale.
• Caching of loaded data and translator objects for efficient access.

Installation

doti18n is available on PyPI.

Instaling:

pip install doti18n

Usage

Here's a basic example of how to use doti18n:

Let's say you have a YAML file like this:

# locales/en.yaml
greeting: "Hello {}!"
farewell: "Goodbye $name!"
items:
    - name: "Item 1"
    - name: "Item 2"
notifications:
    one: "You have {count} new notification."
    other: "You have {count} new notifications."

You can load and use it as follows:

# Import main class
from doti18n import LocaleData

# Create a LocaleData instance
i18n = LocaleData("locales")

# Access translations
print(i18n["en"].greeting("John"))  # Output: Hello John!
print(i18n["en"].farewell(name="Alice"))  # Output: Goodbye Alice!
print(i18n["en"].farewell)  # Output: Goodbye $name!
print(i18n["en"].farewell())  # Output: Goodbye !
print(i18n["en"].items[0].name)  # Output: Item 1
print(i18n["en"].notifications(1))  # Output: You have 1 new notification.
print(i18n["en"].notifications(5))  # Output: You have 5 new notifications.

Project Status

This project is in an early stage of development (Alpha). The API may change in future versions before reaching a stable (1.0.0) release. Any feedback and suggestions are welcome!

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contact

If you have questions, feel free to open an issue on GitHub. Or you can message me on Telegram