Internationalization (i18n) Guide¶
This library provides comprehensive support for translating error messages into different languages for use in multilingual web applications.
Overview¶
All error messages in the sortition algorithms library include:
- English message - for standalone use and backward compatibility
- Error code - a unique identifier for each error type
- Structured parameters - data needed to reconstruct the message in any language
This design allows web applications to translate all error messages while keeping the library independent of any specific translation framework.
For Web Application Developers¶
Basic Approach¶
This library provides translation support for both error messages and run report messages. You can access translation data in the following ways:
Simple Errors (BadDataError, SelectionError, ValueError, etc.)¶
All simple exceptions now include error_code and error_params attributes:
from sortition_algorithms.error_messages import ERROR_MESSAGES
from sortition_algorithms.errors import BadDataError, SelectionError
try:
# ... sortition code
except (BadDataError, SelectionError, ValueError, TypeError, RuntimeError) as e:
if hasattr(e, 'error_code') and e.error_code:
# Look the English template up by code, then translate it
translated_msg = _(ERROR_MESSAGES[e.error_code]) % e.error_params
print(translated_msg)
else:
# Fallback to English message
print(str(e))
Note what the msgid is. N_() marks the English template in
ERROR_MESSAGES, so that template - No '%(column)s' column %(error_label)s
found in %(data_container)s! - is what lands in your .pot and what you pass
to _(). The error code is a lookup key, never a msgid. Passing the code to
_() directly (_(f"errors.{e.error_code}")) would look up a msgid that does
not exist in your catalogue, and gettext would hand the code straight back.
ParseTable Errors (Validation Errors)¶
For ParseTableMultiError exceptions, iterate through the structured error data:
from sortition_algorithms.error_messages import ERROR_MESSAGES
from sortition_algorithms.errors import ParseTableMultiError
# See "A trap to avoid" below for why these are constants rather than
# subscripts written inline in the `_()` calls.
PARSE_ERROR_MULTI_COLUMN = ERROR_MESSAGES["parse_error_multi_column"]
PARSE_ERROR_SINGLE_COLUMN = ERROR_MESSAGES["parse_error_single_column"]
try:
# ... sortition code
except ParseTableMultiError as e:
for sub_error in e.all_errors:
# Access the error code and parameters
if sub_error.error_code:
# Translate the core message
translated_msg = _(ERROR_MESSAGES[sub_error.error_code]) % sub_error.error_params
# Add context (row/column information)
if hasattr(sub_error, 'keys'): # Multi-column error
context = _(PARSE_ERROR_MULTI_COLUMN) % {
'msg': translated_msg,
'row': sub_error.row,
'keys': ', '.join(sub_error.keys)
}
else: # Single-column error
context = _(PARSE_ERROR_SINGLE_COLUMN) % {
'msg': translated_msg,
'row': sub_error.row,
'key': sub_error.key
}
print(context)
else:
# Fallback to English message
print(str(sub_error))
A trap to avoid¶
Babel's Python extractor is token-based: it collects every string literal
between the parens of a _( call. So this line
puts parse_error_multi_column - the dict key - into your .pot as a msgid.
That msgid is dead weight. Nothing ever looks it up, because at runtime _() is
handed the dict value; but it sits in every catalogue, it holds your translated
percentage below 100% for ever, and a translator will either waste effort on it
or fill it with plausible-looking nonsense.
Hoisting the lookup to a constant, as above, keeps the literal out of the _()
call and the artefact out of the catalogue. Subscripts with a variable key -
_(ERROR_MESSAGES[sub_error.error_code]) - contain no literal and are fine.
The signature to grep your catalogues for is a msgid shaped like an identifier:
^msgid "[a-z0-9]+(_[a-z0-9]+)+"$. Worth wiring into CI.
Run Report Messages¶
The RunReport object returned by sortition operations contains informational messages about the process. Each message includes translation data:
from sortition_algorithms.core import run_stratification
from sortition_algorithms.report_messages import REPORT_MESSAGES
success, selected_people, report = run_stratification(
features,
people,
number_people_wanted,
settings,
)
# Iterate through report messages and translate them
for element in report._data:
# Check if this is a message line (not a table or error)
if hasattr(element, "message_code") and element.message_code:
# Look the English template up by code, then translate it
translated_msg = _(REPORT_MESSAGES[element.message_code]) % element.message_params
print(translated_msg)
elif hasattr(element, "line"):
# Fallback to English message
print(element.line)
Alternatively, you can use the serialization feature to extract all translation data:
serialized_report = report.serialize()
for element in serialized_report["_data"]:
if "message_code" in element and element["message_code"]:
# Web app can translate based on message_code
translated_msg = _(REPORT_MESSAGES[element["message_code"]]) % element["message_params"]
elif "line" in element:
# For messages without translation codes, use the English text
fallback_msg = element["line"]
Flask-Babel Integration¶
For Flask applications using Babel for i18n:
1. Configure Babel to Extract Messages¶
Create or update babel.cfg in your web application:
Keywords are not set in the mapping file - Babel takes them on the command
line. N_ is the one you must add; the usual _, gettext and ngettext are
already built in.
2. Extract Messages from Both App and Library¶
Run the extraction command including the sortition library:
pybabel extract -F babel.cfg \
-k N_ \
-o messages.pot \
your_web_app/ \
"$(python -c 'import pathlib, sortition_algorithms as s; print(pathlib.Path(s.__file__).parent)')"
Deriving the library path from the import beats hard-coding it: the Python
version in a site-packages path changes under you, and a hard-coded path that
stops matching fails silently, dropping every library message from the .pot
without an error.
This will extract all marked strings from both your application and the sortition library into a single .pot file.
3. Initialize or Update Translations¶
# For a new language (e.g., French)
pybabel init -i messages.pot -d translations -l fr
# To update existing translations
pybabel update -i messages.pot -d translations
4. Translate the Messages¶
Edit the .po files in translations/<language>/LC_MESSAGES/messages.po:
# English
msgid "No '%(column)s' column %(error_label)s found in %(data_container)s!"
msgstr ""
# French translation
msgid "No '%(column)s' column %(error_label)s found in %(data_container)s!"
msgstr "Aucune colonne '%(column)s' %(error_label)s trouvée dans %(data_container)s!"
5. Compile Translations¶
Available Error Codes¶
The library provides error codes for all validation and runtime errors. Here are the main categories:
Data Validation Errors¶
| Error Code | Parameters | Description |
|---|---|---|
missing_column |
column, error_label, data_container | Required column not found |
duplicate_column |
column, error_label, data_container | Multiple columns with same name |
empty_feature_value |
value_column_name, feature_column_name, feature_name | Blank value in feature data |
value_not_in_feature |
value, feature_column_name, feature_name | Invalid feature value for person |
empty_value_in_feature |
feature_column_name, feature_name | Missing feature value for person |
Numeric Validation Errors¶
| Error Code | Parameters | Description |
|---|---|---|
no_value_set |
field | No value provided for required numeric field |
not_a_number |
value | Value cannot be parsed as a number |
min_greater_than_max |
min, max | Minimum exceeds maximum |
min_flex_greater_than_min |
min_flex, min | Flexible minimum exceeds minimum |
max_flex_less_than_max |
max_flex, max | Flexible maximum less than maximum |
System Errors¶
| Error Code | Parameters | Description |
|---|---|---|
spreadsheet_not_found |
spreadsheet_name | Google Spreadsheet does not exist |
spreadsheet_not_shared |
spreadsheet_name, service_account_email | Google Spreadsheet exists but is not shared with the account |
spreadsheet_read_only |
spreadsheet_name, title, service_account_email | Google Spreadsheet is shared read-only |
not_native_gsheet |
file_name, mimetype, common_name | Drive file is not a native Google Sheet (eg uploaded .xlsx) |
tab_not_found |
tab_name, spreadsheet_title | Worksheet tab not found |
unknown_selection_algorithm |
algorithm | Invalid algorithm specified |
gurobi_not_available |
(none) | Gurobi solver not installed |
See sortition_algorithms/error_messages.py for the complete list of error codes and their message templates.
Report Message Codes¶
The library provides message codes for all run report messages. Here are the main categories:
| Category | Code | Parameters | Description |
|---|---|---|---|
| Data Loading | loading_features_from_string |
(none) | Loading features from string data |
loading_people_from_string |
(none) | Loading people from string data | |
loading_features_from_file |
file_path | Loading features from file | |
loading_people_from_file |
file_path | Loading people from file | |
features_found |
count | Number of features loaded | |
| Algorithm | using_legacy_algorithm |
(none) | Using legacy selection algorithm |
gurobi_unavailable_switching |
(none) | Gurobi unavailable, switching to maximin | |
distribution_stats |
total_committees, non_zero_committees | Distribution statistics | |
| Selection Process | test_selection_warning |
(none) | Warning about non-random test selection |
initial_state |
(none) | Initial state message | |
trial_number |
trial | Current trial number | |
selection_success |
(none) | Selection succeeded | |
selection_failed |
attempts | Selection failed after N attempts | |
| Validation | blank_id_skipped |
row | Blank ID cell found and skipped |
See sortition_algorithms/report_messages.py for the complete list of report message codes and their templates.
Message Reference¶
All translatable strings are defined in:
# Error messages
from sortition_algorithms.error_messages import ERROR_MESSAGES, N_
# Report messages
from sortition_algorithms.report_messages import REPORT_MESSAGES, get_message
Both ERROR_MESSAGES and REPORT_MESSAGES dictionaries map message codes to their English message templates using Python % string formatting.
The N_() function is a no-op marker that identifies strings for extraction by Babel/gettext tools without requiring any translation framework dependency.
The get_message() helper function creates formatted messages from message codes and parameters.
Example: Complete Flask Integration¶
from flask import Flask
from flask_babel import Babel, gettext as _
from sortition_algorithms.core import run_stratification
from sortition_algorithms.error_messages import ERROR_MESSAGES
from sortition_algorithms.errors import ParseTableMultiError, SelectionError
from sortition_algorithms.report_messages import REPORT_MESSAGES
app = Flask(__name__)
babel = Babel(app)
PARSE_ERROR_MULTI_COLUMN = ERROR_MESSAGES["parse_error_multi_column"]
PARSE_ERROR_SINGLE_COLUMN = ERROR_MESSAGES["parse_error_single_column"]
def translate_sortition_error(error):
"""Translate a sortition error into the current language."""
if isinstance(error, ParseTableMultiError):
translated_lines = []
for sub_error in error.all_errors:
if sub_error.error_code:
# Translate core message
core_msg = _(ERROR_MESSAGES[sub_error.error_code]) % sub_error.error_params
# Add context
if hasattr(sub_error, "keys"):
full_msg = _(PARSE_ERROR_MULTI_COLUMN) % {
"msg": core_msg,
"row": sub_error.row,
"keys": ", ".join(sub_error.keys),
}
else:
full_msg = _(PARSE_ERROR_SINGLE_COLUMN) % {
"msg": core_msg,
"row": sub_error.row,
"key": sub_error.key,
}
translated_lines.append(full_msg)
else:
# Fallback to English
translated_lines.append(str(sub_error))
return "\n".join(translated_lines)
else:
# For other errors, use English for now
return str(error)
def translate_run_report(report):
"""Translate run report messages into the current language."""
translated_lines = []
for element in report._data:
if hasattr(element, "message_code") and element.message_code:
# Translate the message
translated_msg = _(REPORT_MESSAGES[element.message_code]) % element.message_params
translated_lines.append(translated_msg)
elif hasattr(element, "line"):
# Fallback to English for messages without translation codes
translated_lines.append(element.line)
# Note: tables and errors would need additional handling
return "\n".join(translated_lines)
@app.route("/select")
def select_committee():
try:
success, selected, report = run_stratification(...)
translated_report = translate_run_report(report)
return {
"status": "success",
"selected": list(selected[0]) if selected else [],
"report": translated_report,
}
except (ParseTableMultiError, SelectionError) as e:
translated_error = translate_sortition_error(e)
return {"status": "error", "message": translated_error}, 400
Testing Translations¶
To test your translations:
- Extract messages:
pybabel extract -F babel.cfg -k N_ -o messages.pot . path/to/sortition_algorithms/ - Check the
.potfile contains sortition error messages and report messages - and no identifier-shaped msgids (see "A trap to avoid") - Initialize test language:
pybabel init -i messages.pot -d translations -l test - Add test translations to verify they appear in your app
- Compile:
pybabel compile -d translations - Trigger errors and run selections in the sortition library and verify translated messages appear
Best Practices¶
- Always provide fallback: If a message code is missing or empty, display the English message from
str(error)orelement.line - Preserve context: When translating ParseTable errors, include row/column information from the error object
- Keep templates synchronized: After upgrading the sortition library, re-extract messages to catch new error codes and report message codes. Because the msgid is the English template, rewording one upstream changes the msgid, and
msgmergewill either fuzzy-match the old translation or drop it. Take care withpybabel update --ignore-obsolete, which discards the old translation outright rather than parking it as#~ - Test all paths: Ensure your translation code handles all error types and report messages the library can generate
- Handle all report elements: RunReport can contain lines, tables, and errors - ensure your translation code handles each type appropriately
Future Enhancements¶
Future versions may add:
- Helper functions for common translation patterns
- Pre-built integration examples for Django, FastAPI, etc.
- Translation utilities for generating .pot files directly from the library
Getting Help¶
If you encounter issues with i18n:
- Check that your
babel.cfgincludes theN_keyword - Verify the extraction command includes the sortition library path
- Ensure error codes in your translation files match those in
error_messages.py - Report issues at: https://github.com/sortitionfoundation/sortition-algorithms/issues