Python

Everything the panel does is available from Python and from Editor Utility Blueprints and Widgets through the editor subsystem TADragomanSubsystem (Blueprint category ta Dragoman). Enable Unreal’s Python Editor Script Plugin to use it from Python.

import unreal

dragoman = unreal.get_editor_subsystem(unreal.TADragomanSubsystem)
report = dragoman.scan(True)

for f in report.findings:
    print(f.severity, f.rule_id, f.culture, f.key, f.message)

Functions work on the target in Project Settings > Plugins > ta Dragoman. A text is identified by its id "Namespace,Key", as in Unreal’s PO files. Where a function takes a list of ids, an empty list means every text of the language.

Checks and reports

Function	Returns	Does
`scan(scan_assets=True)`	`TADragomanReport`	Runs every check of the target. With `scan_assets`, also checks Blueprints, widgets and tables for hardcoded text. Updates the translation memory, like a scan in the panel.
`get_last_report()`	`TADragomanReport`	The report of the last scan, from the panel, Python or the commandlet.
`write_report(report, directory, formats)`	list of paths	Writes the report as HTML and/or JSON (`["html", "json"]`; an empty list writes both). An empty directory writes to `Saved/Dragoman/Reports`.
`check_translation(source, translation, culture, max_length=0)`	list of `TADragomanFinding`	Runs the translation checks on one text pair: placeholders, tags, pattern, whitespace, length, glyphs and glossary.
`check_asset(asset)`	list of `TADragomanFinding`	Hardcoded text, To Text conversions and broken string table references of one loaded asset.
`get_rules()`	list of strings	Rule ids and names, for example `"Placeholder=Placeholder mismatch"`.

Translations

Function	Returns	Does
`set_translation(culture, namespace, key, text)`	`bool`	Writes one translation into the archive and the memory, and removes its machine mark.
`accept_stale(culture, entry_ids)`	`int`	Keeps the current translations of changed source texts. Returns how many were kept.
`accept_machine(culture, entry_ids)`	`int`	Marks machine translations as reviewed.
`fill_from_memory(culture, min_score=1.0, include_stale=False)`	`int`	Fills missing texts from the translation memory. `1.0` uses only the same source text; lower values (down to `0.75` is sensible) also use similar sources, which go in as changed for review. With `include_stale`, changed texts are filled too.
`machine_translate(culture)`	`(written, rejected, error)`	Machine translates the missing texts of the language with the service in the settings and waits for the result (and runs the review pass when the Review Pass setting asks for it). `rejected` counts answers with broken placeholders, tags or plural forms; `error` is empty on success.
`get_machine_notes()`	list of strings	Notes of the last machine translation or review run that didn’t stop it, for example that the DeepL glossary could not be made.
`apply_machine_preset(preset)`	`bool`	Fills in the service, endpoint and model of a preset: `"deepl-free"`, `"deepl-pro"`, `"openai"`, `"azure"`, `"openrouter"`, `"ollama"`, `"lmstudio"` or `"custom"`.
`update_memory()`	`int`	Copies every current translation into the memory file.

Review queue

Function	Returns	Does
`get_review_queue(culture, rescan=True)`	list of `TADragomanQueueItem`	The machine translations waiting for a person, riskiest first (every language when `culture` is empty). With `rescan`, scans the translations first.
`review_machine_translations(culture)`	`(reviewed, error)`	Runs the review pass on the machine translations of the language and waits.
`accept_low_risk(culture, max_risk=30)`	`int`	Accepts the machine translations of the queue with a risk below `max_risk`. Returns how many.
`accept_machine(culture, entry_ids)`	`int`	Marks machine translations as reviewed.
`reject_machine(culture, entry_ids)`	`int`	Removes machine translations again; the texts become missing. Never removes a translation somebody made.
`apply_review_suggestions(culture, entry_ids)`	`int`	Uses the review pass’s suggestions as the translations.

Gather setup and gather

Function	Returns	Does
`find_setup_problems()`	list of `TADragomanSetupProblem`	What breaks the gather or keeps translations out of the game. See Gather setup.
`repair_setup(problem_ids)`	list of strings	Fixes the problems with these ids, or every fixable one with an empty list. Returns what was changed, one line per fix.
`run_gather()`	`TADragomanGatherResult`	Runs Unreal’s Gather Text for the target in its own process and waits. The current translations are saved to the memory first.

Translator files

Function	Returns	Does
`export_package_as(cultures, format, only_todo=True)`	folder path	Writes a translator package from the last report (it scans first if there is none), one file per language: `"csv"`, `"po"`, `"xlsx"`, `"xliff"` (XLIFF 1.2) or `"xliff2"` (XLIFF 2.0). An empty list exports every translated language. Returns an empty string on failure.
`export_package(cultures, po=False, only_todo=True)`	folder path	The same with CSV, or PO with `po=True`.
`import_translations(file, culture, dry_run=True, compile=True)`	`TADragomanImportResult`	Imports a translated CSV, PO, XLIFF (`.xlf`, `.xliff`) or Excel (`.xlsx`) file. Run it with `dry_run=True` first to see what would change. `culture` is used when the file doesn’t name the language; pass `""` otherwise.
`review_and_import(file)`		Opens the panel’s import dialog for the file. Editor only.

Pseudo-localization and compile

Function	Returns	Does
`build_pseudo()`	error string	Adds and fills the pseudo language and compiles it. Returns an empty string on success.
`pseudo_localize(text)`	`str`	Pseudo-localizes one text with the settings, for testing.
`compile(cultures)`	`bool`	Compiles the `.locres` files of these languages, or of every language with an empty list.

Panel

Function	Does
`open_panel()`	Opens the Dragoman panel.
`show_panel_page(page)`	Shows `"texts"`, `"review"`, `"findings"` or `"files"` (the Glossary & memory page).
`show_entry(namespace, key, culture)`	Opens the panel on one text; `culture` is optional. Returns `False` if the text isn’t in the last scan.
`show_review_entry(namespace, key, culture)`	Opens the Review page on one machine translation; `culture` is optional. Returns `False` if the text isn’t waiting for review.

Data types

TADragomanReport

Field	Content
`target_name`, `native_culture`	The target and its native language.
`cultures`	One `TADragomanCultureStats` per language, native first.
`entries`	One `TADragomanEntry` per text.
`findings`	Every `TADragomanFinding`.
`has_manifest`	Whether the target has been gathered.
`assets_scanned`, `scan_time`	Number of checked assets and the scan time (UTC).

TADragomanCultureStats: culture, display_name, native, pseudo, total, translated, missing, stale, machine, errors, warnings, words_to_do.

TADragomanEntry: namespace, key, source, locations, asset_path, note, max_length and translations, one TADragomanTranslation per language in the order of cultures.

TADragomanTranslation: culture, text, status (TADragomanStatus.TRANSLATED, MISSING, STALE, MACHINE or NATIVE), translated_source (for stale texts, the source the translation was made for), suggestion and suggestion_score (from the memory; 1 is the same source), issues (number of errors and warnings).

TADragomanFinding: rule_id, severity (TADragomanSeverity.INFO, WARNING or ERROR), culture (empty when not about one language), namespace, key, asset_path, location, message, text.

TADragomanImportResult: success, dry_run, file, culture, format (for example "XLIFF 1.2"), tool (the tool that wrote an XLIFF file), file_language (the language code as the file writes it, for example "ja-JP"), error and rows. Each TADragomanImportRow has culture, namespace, key, source, current, imported, action ("new", "changed", "same" or "skipped"), problem, blocked and line.

TADragomanQueueItem: culture, namespace, key, source, translation, risk (0 to 100), level ("high", "medium" or "low"), reasons and reason_points (what each reason adds), verdict ("ok", "warn", "fail", or empty when not reviewed), review_score (-1 when not reviewed), review_issues, review_suggestion, note, max_length, asset_path, location.

TADragomanSetupProblem: id (for example MissingManifestFile), severity, title, detail, can_fix, fix (what the repair does) and items (the dependency, files or assets it is about).

TADragomanGatherResult: success, exit_code, errors, warnings, hints (explanations for known errors), log_file (the full output under Saved/Dragoman/Logs), seconds, error, and steps and steps_done (the gather steps of the target’s config, and how many of them the log reported as done).

Examples

Coverage per language

import unreal

dragoman = unreal.get_editor_subsystem(unreal.TADragomanSubsystem)
report = dragoman.scan(False)  # translations only, faster

for c in report.cultures:
    if c.native or c.pseudo:
        continue
    done = c.translated + c.machine
    print(f"{c.display_name}: {done}/{c.total} ({100 * done // max(c.total, 1)}%), {c.words_to_do} words to do")

Import a translator’s file after a dry run

result = dragoman.import_translations("C:/In/Game_de.csv", "", True, False)  # dry run
blocked = [r for r in result.rows if r.blocked]
for r in blocked:
    print(f"line {r.line}: {r.key}: {r.problem}")

if result.success and not blocked:
    dragoman.import_translations("C:/In/Game_de.csv", "", False, True)  # write and compile

Accept changed texts and fill repeats

dragoman.scan(False)
kept = dragoman.accept_stale("de", ["UI,Btn_Start", "UI,Btn_Quit"])
filled = dragoman.fill_from_memory("de", 1.0, False)
dragoman.compile(["de"])
print(f"kept {kept}, filled {filled}")

Repair the setup, gather and export XLIFF

for problem in dragoman.find_setup_problems():
    print(problem.id, problem.title, problem.fix)
dragoman.repair_setup([])                                  # every fixable problem
gather = dragoman.run_gather()
print(gather.success, gather.errors, gather.warnings, gather.log_file)
folder = dragoman.export_package_as(["de"], "xliff2", True)  # csv, po, xlsx, xliff, xliff2; to-do only

Machine translate and work through the review queue

written, rejected, error = dragoman.machine_translate("de")
reviewed, error = dragoman.review_machine_translations("de")
for item in dragoman.get_review_queue("de", True):
    print(item.risk, item.level, item.key, item.translation, item.reasons)
dragoman.accept_low_risk("de", 30)
dragoman.compile([])

Check one text

for f in dragoman.check_translation("Welcome back, {PlayerName}!", "Willkommen zurück!", "de", 0):
    print(f.rule_id, f.message)   # Placeholder Missing {PlayerName}.