feature:translate

Extract, initialize, or compile translations for one or all features of the active product.

Usage

splent feature:translate [<feature>] [--extract] [--init LOCALE] [--compile]

Options

Option	Description
`<feature>`	Optional. Target a single feature (e.g. `auth` or `splent_feature_auth`). If omitted, operates on all features declared in `pyproject.toml`.
`--extract`	Extract translatable strings from Python and Jinja2 files into `translations/messages.pot`.
`--init LOCALE`	Initialize or update a locale (e.g. `--init es`). Creates `translations/<locale>/LC_MESSAGES/messages.po` from the `.pot` template. If the locale directory already exists, merges new strings via `pybabel update`.
`--compile`	Compile all `.po` files to `.mo` binary files. The `.mo` files are what Flask-Babel reads at runtime.

At least one of --extract, --init, or --compile must be provided.

Examples

Extract translatable strings from the auth feature:

splent feature:translate auth --extract

Extract from all features:

splent feature:translate --extract

Initialize Spanish translations for the auth feature:

splent feature:translate auth --init es

Compile translations for all features:

splent feature:translate --compile

Combine multiple operations in one invocation:

splent feature:translate auth --extract --init es --compile

Step-by-step workflow

A typical translation workflow for a new locale:

# 1. Extract all translatable strings
splent feature:translate auth --extract

# 2. Create the locale (or update if it already exists)
splent feature:translate auth --init es

# 3. Edit the .po file with translations
#    src/splent_io/splent_feature_auth/translations/es/LC_MESSAGES/messages.po

# 4. Compile to .mo for runtime use
splent feature:translate auth --compile

After adding new translatable strings to your code, re-run --extract and then --init <locale> to merge the new strings into existing .po files without losing previous translations.

What it does

For each targeted feature, the command:

Resolves the feature’s source directory – checks the workspace root (editable) first, then .splent_cache (pinned).
--extract: Creates babel.cfg if missing (default: extract from **.py and **/templates/**.html), then runs pybabel extract to produce translations/messages.pot.
--init: Runs pybabel init (new locale) or pybabel update (existing locale) using the .pot as input.
--compile: Runs pybabel compile to generate .mo files from all .po files in the feature’s translations/ directory.

Requirements

A product must be selected (SPLENT_APP set).
For --init, a .pot file must exist – run --extract first.
Flask-Babel and Babel must be installed in the environment.

Run this command inside the CLI container, not on the host machine.