Install & Compatibility
Where this runs
tested against v3.17.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.133s · 71.2MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 4.1s · import 0.130s · 64MB
63MB installed
● package 63MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PoFile
✓ from translate.storage.po import pofile
The PoFile class for working with Gettext PO files is found within the 'pofile' submodule of 'translate.storage'.
XliffFile
✓ from translate.storage.xliff import xliff
Similar to PoFile, XliffFile is located within its respective submodule for XLIFF format handling.
This quickstart demonstrates how to programmatically load, inspect, and modify a Gettext PO file using the Translate Toolkit's API. It creates a temporary PO file, reads its content, prints individual translation units, shows how to update a target string, and optionally saves the changes to a new file, finally cleaning up the temporary files.
import os
from translate.storage import po
# 1. Create a dummy PO file for demonstration
po_content = '''
msgid ""
msgstr ""
"Project-Id-Version: Example Project 1.0\n"
"Content-Type: text/plain; charset=UTF-8\n"
msgid "Hello, world!"
msgstr "¡Hola, mundo!"
msgid "Welcome to our application."
msgstr "Bienvenido a nuestra aplicación."
'''
with open("example.po", "w", encoding="utf-8") as f:
f.write(po_content)
# 2. Load the PO file
try:
po_file = po.pofile.PoFile("example.po")
print(f"Loaded PO file with {len(po_file.units)} translation units (including header).")
# 3. Iterate and print translation units
for unit in po_file.units:
if not unit.isblank(): # Skip the header unit
print(f"---\nOriginal: '{unit.source}'\nTranslated: '{unit.target}'")
# 4. Modify a translation unit (example)
if len(po_file.units) > 1: # Ensure there's at least one real unit after header
first_translatable_unit = po_file.units[1]
print(f"\nModifying unit: '{first_translatable_unit.source}'")
first_translatable_unit.target = "¡Saludos, universo!"
print(f"New translation: '{first_translatable_unit.target}'")
# 5. Save the modified PO file (optional)
po_file.save("example_modified.po")
print("\nModified file saved to example_modified.po")
except Exception as e:
print(f"An error occurred: {e}")
finally:
# 6. Clean up dummy files
if os.path.exists("example.po"):
os.remove("example.po")
if os.path.exists("example_modified.po"):
os.remove("example_modified.po")
print("\nCleaned up dummy files.")
translate-toolkit --version
Errors
Common errors & fixes
UnicodeDecodeError: 'charmap' codec can't decode byte 0x81 in position X: character maps to <undefined>
File encoding mismatch, where the default system encoding or an assumed encoding (e.g., UTF-8) does not match the actual encoding of the localization file.
fixExplicitly specify the correct encoding when reading files (e.g., `PoFile(filename, encoding='iso-8859-1')`). The toolkit has improved charset detection in newer versions, but explicit specification is always safer for diverse inputs.
Machine translation errors due to Django/Python template variables (e.g., `{{ variable }}`) being translated or mangled.
Automatic tokenization in machine translation services often breaks or translates placeholders/variables, as they are not recognized as non-translatable tokens.
fixBefore sending to machine translation, pre-process your localization files to replace template variables with simple, unique placeholders (e.g., `_VAR_1_`). After translation, post-process to restore the original variables.
Upgrade
Version history
3.19.11latest on PyPI · released May 28, 2026
Audit
Dependencies
lxmlrequiredRequired for full XML/XLIFF processing capabilities, especially for robust parsing and serialization.
pycountryoptionalEnables translation of language names (e.g., 'English (South Africa)') within the `lang.data` module.
enchantoptionalProvides spellchecking functionality within the toolkit's quality assurance tools.
RapidFuzzoptionalUsed for optimized Levenshtein distance calculations in fuzzy matching operations (since version 3.19.0).