polyglot-ui 0.1.0

Features

• Filter untranslated help texts by checking if their Python object path is accessible

• Filter untranslated strings from .po files by checking occurrence comments against sys.modules

• Extract all untranslated strings from HTML template sources

• Translate using Google Gemini API with batch processing and resume capability

• Update and compile .po files automatically

• Support for plural forms and format specifier preservation

Installation

From PyPI:

pip install polyglot-ui

For development:

pip install -e .

Requirements:

• Python 3.8+

• GEMINI_API_KEY environment variable for translation:

  export GEMINI_API_KEY="your-key-here"

Get your API key from https://ai.google.dev/

Quick Start

# 1. Generate .po files (if not done)
inv mm

# 2. Extract untranslated strings (requires Django context)
python manage.py run $(which polyglot-ui) helptexts \
    -p lino -l lino -L bn -o translateables.json

# 3. Translate
polyglot-ui translate -i translateables.json -o translated.json

# 4. Update .po files
polyglot-ui update -t translated.json -l lino --lang bn

Commands

* Required only when filtering by sys.modules (without –all flag)

Detailed Usage

python manage.py run $(which polyglot-ui) helptexts \
    -p lino_pronto -l lino_pronto -L bn -o helptexts.json

python manage.py run $(which polyglot-ui) modules \
    -p lino -l lino -L bn -o modules.json

polyglot-ui modules -p lino -l lino -L bn -o all_modules.json --all

polyglot-ui html -l lino -L bn -o html.json

export GEMINI_API_KEY="your-key"
polyglot-ui translate -i translateables.json -o translated.json

polyglot-ui update -t translated.json -l lino --lang bn

polyglot-ui compile /path/to/django.po

Workflow Example

# Setup
export GEMINI_API_KEY="your-key"
cd /path/to/project
inv mm  # Generate .po files

# Extract (requires Django context)
python manage.py run $(which polyglot-ui) helptexts \
    -p lino -l lino -L bn -o helptexts.json
python manage.py run $(which polyglot-ui) modules \
    -p lino -l lino -L bn -o modules.json

# Extract HTML (no Django context)
polyglot-ui html -l lino -L bn -o html.json

# Translate
polyglot-ui translate -i helptexts.json -o t_helptexts.json
polyglot-ui translate -i modules.json -o t_modules.json
polyglot-ui translate -i html.json -o t_html.json

# Update .po files
polyglot-ui update -t t_helptexts.json t_modules.json t_html.json \
    -l lino --lang bn

How It Works

Prerequisites

.po files must exist (generated by inv mm command).

Smart Filtering

Shared packages like lino and lino_xl contain thousands of strings. Each app only uses a subset. Polyglot UI filters by:

1. Help texts (helptexts):

   • Reads help_texts dict from locale_root/help_texts.py

   • Keys are Python object paths: "lino.modlib.users.User.username"

   • Checks if object is accessible by iteratively using getattr on sys.modules

   • Only includes help texts for accessible objects

2. Module strings (modules):

   • Reads occurrence comments from .po file: #: lino/modlib/users/models.py:123

   • Converts file path to module name: lino.modlib.users.models

   • By default: Checks if module is in sys.modules (requires Django context)

   • With --all flag: Extracts all strings without filtering (no Django context needed)

   • Only includes strings from imported modules (or all with --all)

3. HTML strings (html):

   • Checks if occurrence comment ends with .html

   • No filtering - extracts ALL HTML strings

Django Context

Commands requiring python manage.py run:

• helptexts - needs sys.modules to check object accessibility

• modules - needs sys.modules to check module imports (unless --all flag is used)

Other commands run standalone.

Tips

• Run inv mm first to generate/update .po files

• Organize output: helptexts.json, modules.json, html.json

• Batch size: 200 (default) works well; reduce if API limits hit

• Translation is resumable - rerun if interrupted

• Never commit GEMINI_API_KEY to version control

Troubleshooting

• “GEMINI_API_KEY not set”: Export your API key

• “Module not found”: Use python manage.py run for commands requiring Django context

• “No module named ‘google.genai’”: Run pip install google-genai

• Incomplete translations: Check API limits, network; rerun to resume

License & Support

GPL-2.0

Contributions welcome via Pull Request.

Changelog

0.1.0 (2026-02-08)

• Initial release

• Filter untranslated strings by checking sys.modules and object accessibility

• Google Gemini API integration

• Plural forms and format specifier preservation