edX Internationalization Tools

2.0.0 verified Mon Apr 27 auth: no python

edX Internationalization Tools is a Python library providing utilities for extracting, generating, and managing translation files (PO, MO, XLIFF) in edX projects. It wraps Babel, polib, and lxml. Current version 2.0.0 drops Python 3.11 support. Release cadence is irregular, with major versions driven by Python version drops.

pip install edx-i18n-tools

Common errors

error ModuleNotFoundError: No module named 'i18n_tools' ↓

cause The package is installed as 'edx-i18n-tools' but imported as 'i18n_tools'. Users mistakenly try to import 'edx_i18n_tools'.

fix

Use 'import i18n_tools' (or 'from i18n_tools import ...').

error AttributeError: module 'i18n_tools' has no attribute 'extract' ↓

cause In v2.0.0, the 'extract' function was removed. The correct API is 'extract_i18n'.

fix

Replace 'i18n_tools.extract(...)' with 'i18n_tools.extract_i18n(...)'.

Warnings

breaking Version 2.0.0 drops support for Python 3.11. Only Python 3.12+ is supported. ↓

fix Upgrade Python environment to 3.12 or later.

deprecated The 'extract' command-line entry point has been removed in v2.0.0. Use the Python API instead. ↓

fix Replace shell script calls to 'extract' with Python code using i18n_tools.extract_i18n().

gotcha The library depends on lxml which may require system libraries (libxml2, libxslt). Pip install may fail on minimal systems. ↓

fix Install system dependencies: apt-get install libxml2-dev libxslt1-dev (Debian/Ubuntu) or brew install libxml2 libxslt (macOS).

Imports

extract_i18n
```
from i18n_tools import extract_i18n
```
Common mistake: using underscores instead of hyphens in package name, or using 'edx_i18n_tools' as the module.
generate_po
```
from i18n_tools import generate_po
```
generate_po is exposed directly at package level, not from a submodule.
I18nToolConfig
```
from i18n_tools.config import I18nToolConfig
```
I18nToolConfig is in the config submodule, not directly in i18n_tools.

Quickstart

Extract translatable strings from Python source files into a PO file.

from i18n_tools import extract_i18n

# Extract translatable strings from source files
extract_i18n(
    source_paths=['./my_project'],
    output_file='./locale/messages.po',
    keywords=['_', 'gettext', 'ngettext:1,2']
)
print('Translation extraction complete.')