accetra 0.3.0

A flexible XML/JSON language loader

Accetra - Multilingual Language Loader

Accetra is a lightweight and efficient language loader that supports loading translations from XML and JSON files. It allows for automatic fallback, variable replacements, and has an organized structure for easy extensibility. This library is ideal for applications that need to support multiple languages.

---

🚀 Features

• Multi-format Support: Load translations from XML and JSON files.
• Fallback Mechanism: Automatically fall back to another language if a key is missing.
• Variable Replacement: Replace variables in strings (e.g., {username} becomes Alice).
• Metadata Extraction: Retrieve metadata like language code, authors, and version.
• Extensibility: Easily add support for more formats or customization.
• Clear Structure: Organize translations into sections (e.g., windows, errors, etc.).
• CLI: Create and Validate language files.

---

🧑‍💻 Installation

1. Install via PyPI (Recommended)

You can install Accetra directly from PyPI:

pip install accetra

2. Install from Source

If you want to contribute or modify the library, you can install it from the source in editable mode:

git clone https://github.com/yourusername/accetra.git
cd accetra
pip install -e .

---

🎯 Usage

CLI

Validate File: accetra validate <path>

Create template: accetra template <path (.)> <json/xml>

Accetra supports loading languages from both XML and JSON formats. Below are examples of how to use both formats.

XML Example

<language>
    <meta>
        <code>en</code>
        <name>English</name>
        <authors><author>John Doe</author></authors>
        <version>1.0</version>
        <description>English Language Pack</description>
    </meta>
    <general>
        <entry id="app.welcome">
            <text>Welcome, {username}!</text>
        </entry>
    </general>
</language>

Load and use an XML language file:

from accetra.xml_loader import XmlLanguageLoader

# Initialize loader with primary and fallback languages
lang = XmlLanguageLoader("languages/en.xml", "languages/de.xml")

# Get translated text with variable replacement
text = lang.get_text("general.app.welcome", username="Alice")
print(text)  # Output: "Welcome, Alice!"

JSON Example

{
  "meta": {
    "code": "en",
    "name": "English",
    "authors": ["John Doe"],
    "version": "1.0",
    "description": "English Language Pack"
  },
  "general": {
    "app.welcome": {
      "text": "Welcome, {username}!"
    }
  }
}

Load and use a JSON language file:

from accetra.json_loader import JsonLanguageLoader

# Initialize loader with primary and fallback languages
lang = JsonLanguageLoader("languages/en.json", "languages/de.json")

# Get translated text with variable replacement
text = lang.get_text("general.app.welcome", username="Alice")
print(text)  # Output: "Welcome, Alice!"

---

🧑‍💼 Functions and Methods

Base Class: BaseLanguageLoader

The base class provides the core functionality for loading translations and handling variable replacement.

• __init__(self, primary_lang_file, fallback_lang_file=None):
  Initialize the loader with primary and optional fallback language files.

• get_text(self, entry_id, **variables):
  Retrieve the translated text for a specific entry, applying any provided variable replacements.

• get_tooltip(self, entry_id, **variables):
  Retrieve the tooltip text for a specific entry, applying any provided variable replacements.

XML Loader: XmlLanguageLoader

Inherits from BaseLanguageLoader, designed for loading XML-based translation files.

• load_language(self, lang_file, is_fallback=False):
  Load the specified XML language file.

• _load_metadata(self, meta):
  Extract metadata from the XML file (e.g., code, name, authors).

• _load_entries(self, section, prefix="", is_fallback=False):
  Load translation entries from a specific section in the XML.

JSON Loader: JsonLanguageLoader

Inherits from BaseLanguageLoader, designed for loading JSON-based translation files.

• load_language(self, lang_file, is_fallback=False):
  Load the specified JSON language file.

• _load_metadata(self, meta):
  Extract metadata from the JSON file (e.g., code, name, authors).

• _load_entries(self, section, prefix="", is_fallback=False):
  Load translation entries from a specific section in the JSON.

---

🤝 Contributing

We welcome contributions to Accetra! If you would like to contribute, please follow these steps:

1. Fork the repository:
   Click the "Fork" button at the top of the page to create your own copy of the repository.

2. Create a new branch:
   In your forked repository, create a new branch for your changes:

   git checkout -b feature/my-new-feature
   

3. Make your changes:
   Make your changes to the code. Add tests for new features or bug fixes.

4. Commit your changes:
   Once you're happy with your changes, commit them:

   git commit -am 'Add new feature'
   

5. Push your changes:
   Push your changes to your forked repository:

   git push origin feature/my-new-feature
   

6. Create a pull request:
   Go to the original repository and create a pull request. We'll review it and merge it into the main branch if everything looks good.

---

📝 License

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

---

📢 Contact

If you have any questions or suggestions, feel free to open an issue or contact the maintainers:

• AK (TRCLoop): GitHub Profile

---

Happy coding! 😊