Bethesda Strings Editor

AI-assisted localization tool for Bethesda game files (Starfield). Translates .strings, .dlstrings, .ilstrings, BA2 archives, ESP/ESM plugin files, and Starfield interface TXT files between all 12 supported languages using a locally-running Ollama model or the Claude API, with a full quality-checking and review workflow.

---

Ollama models

Model	Purpose	Hub
translategemma3-st	Game string translation — Gemma 3 12B fine-tune (6.5 GB)	local GGUF
translategemma3-st-2	Same fine-tune, reduced context (8 k) for GPU inference	local GGUF
mamaylm	MamayLM Gemma 3 12B IT v2.0 — INSAIT Ukrainian fine-tune	local GGUF
gemma4-opus48-st	Gemma 4 12B IT fine-tuned on Claude Opus reasoning data	local GGUF
qcgemma4-st	Translation quality checking — Gemma 4 E4B fine-tune (16 issue codes)	0xra/bethesda-qc

The custom translation fine-tunes are not published on any hub — there is no ollama pull for translategemma3-st. To translate, use either the Claude API backend or a local GGUF, as below.

Option A — Claude API (no local model)

Enter your Anthropic API key in Settings → Claude AI and pick Haiku 4.5 / Sonnet 4.6 / Opus 4.8. No Ollama or GPU required — this is the quickest way to get translating.

Option B — local Ollama model from a GGUF

Any Gemma-3 / instruct GGUF works with the app's prompts (the app supplies its own system prompt and overrides every generation parameter at runtime). For Ukrainian, the publicly available MamayLM fine-tune is a good default:

# 1. Download a GGUF — e.g. MamayLM (Ukrainian) from HuggingFace:
#    https://huggingface.co/INSAIT-Institute/MamayLM-Gemma-3-12B-IT-v2.0
#    (or use any *.gguf you already have)

# 2. Edit the bundled Modelfile and point its FROM line at your file:
#    FROM /path/to/your-model.Q4_K_M.gguf

# 3. Build the model, then select it in Settings → Ollama:
ollama create translategemma3-st -f Modelfile

Modelfile, Modelfile.mamaylm, and Modelfile.gemma4-opus48 are templates — set the FROM path to your GGUF before running ollama create. The created model name is arbitrary; just select whatever you created in Settings → Ollama.

Optional — AI quality-check model (published on the hub)

ollama pull 0xra/bethesda-qc
ollama cp 0xra/bethesda-qc qcgemma4-st

---

Supported languages

All 9 official Starfield languages plus Russian, Ukrainian, and Korean:

Code	Language
en	English
de	German
es	Spanish
fr	French
it	Italian
ja	Japanese
ko	Korean
pl	Polish
ptbr	Portuguese (Brazil)
zhhans	Chinese (Simplified)
ru	Russian
uk	Ukrainian

Each language pair has a dedicated system prompt with register rules, script conventions, and native examples.

---

Features

Translation

• Parallel AI translation via Ollama with configurable concurrency (default 10 workers)
• Claude API backend — drop-in alternative to Ollama; select Haiku 4.5, Sonnet 4.6, or Opus 4.8 in Settings
• AI-fix mode — instead of retranslating from source, sends the existing flawed translation + QC issue descriptions to the model for targeted correction; faster and more precise than a full retranslation
• Language-pair prompts — dedicated system prompts for every source→target combination with register rules, script conventions, and native examples
• Translation memory — known strings are looked up before calling the model, so they are never retranslated
• Translation cache — SHA-256-keyed JSON cache (up to 50,000 entries) persisted across sessions
• Term protector — 8,000+ Starfield-specific terms are replaced with placeholder tokens before the AI sees the text and restored afterward, preventing mistranslation of proper nouns
• Pipeline post-processing — per-string passes after every translation: game tag restoration, case matching, line-prefix preservation, newline structure repair, mixed-script repair, guillemet close-quote enforcement
• Glossary system — CSV/TBX/JSON glossary with in-app editor, term suggestions dock, and automatic injection into AI prompts
• Character Persona Profiling — assign a voice profile to any string or quest (Freestar Ranger, SysDef Officer, Crimson Fleet Pirate, House Va'ruun Zealot, UC Civilian, Robot/Automaton, Narrator, or custom); each profile overrides the AI system prompt and temperature
• Lore RAG — local SQLite FTS5 lore database (built-in UESP downloader); relevant faction, location, and character articles are retrieved per string and injected into the AI prompt
• Pre-translation estimator — scores each string 0–100 to predict translation difficulty before the AI runs
• Skip string types — exclude Book, Note, or other categories from AI batch translation
• Protect named entities — opt-in setting to extend term protection to faction/ship/character names inferred from the loaded file
• Claude pre-flight cost estimator — shows token count and estimated cost before starting a batch translation

File support

• Binary string files: .strings (null-terminated), .dlstrings / .ilstrings (length-prefixed)
• BA2 archives: read and write Starfield v2 BA2 files (GNRL type, zlib-compressed); picker dialog for multi-entry archives
• ESP/ESM plugins: non-localized plugins where text is stored directly in field buffers
• ESP/ESM Mod Update Migration (Translation → Mod Update Migration) — diff an old and new version of a plugin keyed on FormID and carry existing translations forward to the updated release (xTranslator-style); risk-coloured 7-column diff with changed-only filter and CSV/HTML export
• VMAD script-property analysis (Translation → Script Property Analysis) — parses the Papyrus script-property strings attached to records, classifies each value as translatable / review / locked (resource paths, event names, identifiers), and byte-splices only the edited values so unmodelled script structures survive untouched; works on both localized and non-localized plugins
• Starfield interface TXT: translate_en.txt / translate_ru.txt key=value interface string files
• xTranslator SST XML: import/export in xTranslator format (match by sID, fallback to source text)
• Drag-and-drop file loading with format validation
• NexusMods Translation Browser — search NexusMods for existing translation mods, browse their files, and import .strings/.dlstrings/.ilstrings directly as a Translation Memory or merge into the current file; zip, 7z, and rar archives are automatically extracted; free-account downloads via browser cookies (curl-cffi); account sign-in uses the official browser-based Single Sign-On flow (no API key to paste — the app is a registered NexusMods application)
• NexusMods upload — v3 multipart upload client with presigned S3 URLs (File → Upload to NexusMods)

Quality assurance

• Quality checker — 20+ checks: missing/extra game tags, empty or untranslated strings, source-language leakage, English leak, suspicious length ratios, newline mismatches, truncated AI output, AI artifact prefixes, encoding failures, unclosed guillemets, unmatched brackets, script coverage (CJK), and more
• RU→UK false-positive reduction — UNTRANSLATED check uses Russian-exclusive character detection (ы/э/ё/ъ) and minimum word-count threshold to avoid flagging legitimately identical short words; length-ratio skip applies only to short Cyrillic sources (abbreviation expansions)
• Hunspell spell-check — per-language SPELL_ERROR warnings; uses system dictionaries on Linux and app-bundled dictionaries on Windows/macOS (populate via scripts/fetch_dictionaries.py)
• AI quality model (qcgemma4-st) — fine-tuned Gemma 4 E4B that detects 16 issue codes with chain-of-thought reasoning and structured VERDICT: GOOD / ISSUES_FOUND output with AUTOFIX/RETRANSLATE recommendations
• Font & Glyph Checker — parses Scaleform SWF font atlases and TTF/OTF cmap tables; flags translation characters that will render as squares in-game and suggests auto-fixable substitutes
• Auto-Fix All — one-click batch application of all mechanically correctable issues (whitespace, capitalization, character substitution, missing newlines, truncated translations, unclosed guillemets)
• Per-code hide filter — suppress specific QC issue codes from the results table for the current session
• Retranslation queue — strings flagged by QC are queued and retranslated with a per-string hint describing what went wrong
• Error-code filter — filter QC results by code (MISSING_TAGS, NEWLINE_COUNT_MISMATCH, etc.)
• Consistency checker (Ctrl+Alt+K) — finds the same source string translated differently across the file, with canonical-form picker and batch replace
• Ukrainian gender agreement checker (Ctrl+Alt+G) — detects adjective/noun gender mismatches using a noun-gender dictionary, with inline fix suggestions
• ти/ви register consistency — informal ти / formal ви is kept consistent per speaker inline by the translation system prompt (shared by the Ollama and Claude backends), so mixed address never enters the output in the first place
• Plugin validator — scans ESP/ESM for NPC dialogue camera bugs: missing Localized flag, stray DIAL/SCEN/INFO records, ONAM overrides, missing master dependencies

Review tools

• Visual Context Preview (Ctrl+Shift+P) — dockable panel that renders the current string inside a faithful recreation of the Bethesda UI using actual game fonts extracted from fonts_uk.swf / fonts_en.swf; pixel-exact borders, noise tile, and dark gradient from dialoguemenu.swf; auto-detects context type (Dialogue, Quest, Book, Note, Terminal, UI); colour-coded overflow indicator; Source/Translation/Both view modes
• Dialogue Tree Visualizer — interactive quest → topic → response node graph (Translation → Dialogue Tree) with Starfield dark-space visual theme; click any node to jump to that string in the table
• Audio / TTS Preview (Ctrl+Shift+A) — dockable panel with eSpeak-NG and Piper backends; synthesizes a TTS read-out of the translation so timing can be compared against the original game audio; colour-coded timing bar (green ≤ 110 %, orange ≤ 130 %, red > 130 %)
• Native Starfield voice playback — decodes the original Wwise .wem voice clip for a dialogue line straight from the game's *Voices*.ba2 archives (FormID → voice clip, via vgmstream-cli) and plays it back in the audio panel alongside the TTS read-out; in ESP/ESM mode the row's FormID auto-fills
• Speaker (NPC) panel — shows who voices the selected dialogue line (name, gender, faction, category, raw voice type, plus "also voiced by" for shared lines) by parsing the Wwise voice-type folder name; tabified with the Audio panel
• Version comparison — diff two game versions, migrate unchanged translations, export CSV/HTML reports; batch folder comparison
• Diff viewer — side-by-side word-level or character-level diff; editable right pane with live diff update; HTML export
• Advanced search — regex and fuzzy search across source and translation columns; batch Find & Replace

UI / workflow

• Zen / Focus Mode (F11) — full-screen distraction-free editor with large source and translation panels, pending-string counter, per-string status badge
• Multi-monitor / detached panes — Translation Editor dock (Ctrl+Shift+E) floats to any monitor; Pop Out String List (Ctrl+Shift+L) opens a second table window sharing the same selection model
• Claude AI Assistant dock (Ctrl+Shift+C) — chat about the current string and apply Claude's suggested translation with one click; optionally connect remote MCP servers (Settings → Claude MCP Servers) so Claude can call external tools while you chat, via the Messages API MCP connector
• Command palette (Ctrl+K) and vim-style navigation (j/k, G)
• Translation sessions — named work sessions with persistent search/filter state (Ctrl+Shift+N new, Ctrl+Shift+S save)
• Macro recorder (Ctrl+M) — record and replay sequences of edit operations as named macros
• Keyboard shortcuts editor — rebind any action
• F7 → jump to next untranslated; Ctrl+Enter → approve; Ctrl+R → reject
• Encoding detection — auto-detects UTF-8, CP1251, CP1252, CP1250, GBK/GB2312, BOM variants; override per-file
• Themes — 16 built-in themes: Slate, Midnight, Nord, Dracula, Catppuccin, Light, Solarized Dark, Solarized Light, Gruvbox, Tokyo Night, Monokai, One Dark, Sepia, Starfield, Starfield Terminal, High Contrast; plus custom QSS file support
• GPU monitor — status bar widget showing GPU utilisation, VRAM usage, and temperature (AMD via Linux sysfs; NVIDIA via nvidia-smi on Linux/Windows/macOS; auto-hides if no GPU found)
• Ollama model auto-detection — the model dropdown in Settings loads installed models automatically and keeps refreshing while the window is open, so a model pulled with ollama pull shows up without clicking Refresh
• Ollama force-stop — frees a wedged GPU by restarting the Ollama service; on Linux a privileged restart uses the app's own Qt-themed password dialog (sudo -S, with askpass/pkexec fallback), on Windows it stops the service via taskkill with no console flash
• UI translations — interface available in Ukrainian ✓, German, Spanish, French, Polish, Czech, Korean (community WIP)
• Cross-platform desktop notifications on batch completion — notify-send/D-Bus on Linux, native system-tray balloons on Windows and macOS
• Native OS integration — native Explorer/Finder file dialogs on Windows/macOS; config stored in the OS-native location (%APPDATA% on Windows, ~/Library/Application Support on macOS, $XDG_CONFIG_HOME/~/.config on Linux) with owner-only file permissions
• "What's New" panel — recent GitHub release notes are fetched and rendered on the welcome screen after the welcome card
• Automatic update check — checks the GitHub releases API on startup and offers to download a newer build (toggle in Settings)
• Crash recovery — periodic auto-save; recovery dialog offered at startup if the previous session ended unexpectedly
• Security audit log — append-only JSON-lines file recording file operations and translation batches; API keys stored in system keyring with AES-256-GCM file fallback

---

Requirements

• Python 3.10+
• Ollama running locally (or a Claude API key for the Claude backend)
• Audio playback is auto-detected per platform: Linux uses paplay, ffplay, or aplay; macOS uses afplay (or ffplay); Windows uses ffplay or the built-in PowerShell WAV player
• Native Starfield voice playback requires vgmstream-cli on PATH (decodes Wwise .wem clips)

pip install -r requirements.txt

Core dependencies: PySide6>=6.6, requests>=2.31, cryptography>=43.0, anthropic>=0.25

Optional:

• keyring>=25.0 — API key storage in system keyring
• hunspell>=0.5.5 or spylls>=0.1.7 — spell-check engine (hunspell CLI used as fallback); run scripts/fetch_dictionaries.py to bundle Hunspell dictionaries for Windows/macOS
• curl-cffi>=0.7 — free-user NexusMods downloads via browser cookies

---

Running

python main.py

Logs are written to both stdout and translator.log in the project root.

---

Project structure

bethesda_strings/              Pure Python parsing library (no Qt dependency)
  core.py                      Binary parser/writer for .strings/.dlstrings/.ilstrings
  ba2_handler.py               BA2 archive reader/writer (Starfield v2, FO4 v1)
  esp_handler.py               ESP/ESM plugin parser (non-localized plugins)
  esp_diff.py                  ESP/ESM mod-update migration (FormID-keyed diff)
  vmad_handler.py              VMAD Papyrus script-property parser/classifier/byte-splice editor
  wwise_voice.py               Wwise voice index — FormID → original .wem clip from Voices BA2
  txt_handler.py               Starfield interface TXT parser (translate_en/ru.txt)
  xml_handler.py               xTranslator SST XML import/export
  encoding.py                  Encoding detection and conversion
  version_diff.py              Game-version diff and translation migration
  character_profiles.py        Character persona profile definitions
  font_checker.py              SWF/TTF glyph coverage checker (library layer)
  lore_db.py                   SQLite FTS5 lore database and UESP downloader
  dialogue_tree.py             Quest → Topic → Response tree parser

gui/                           PySide6 application layer
  main_window.py               Top-level window, file I/O, translation orchestration
  ollama_worker.py             QThread worker — parallel calls, per-language prompts, AI-fix mode
  ollama_control.py            Ollama service force-stop/restart helper (sudo/taskkill)
  sudo_dialog.py               Qt-themed sudo password prompt (sudo -S over stdin)
  claude_translation_worker.py Claude API drop-in replacement for OllamaWorker
  claude_chat_panel.py         Dockable AI assistant chat panel
  gpu_monitor.py               Status bar GPU utilisation widget (AMD sysfs + NVIDIA nvidia-smi)
  visual_context_preview.py    Game-accurate string rendering using extracted SWF fonts/assets
  dialogue_tree_dialog.py      Interactive quest → topic → response node graph
  audio_preview_panel.py       TTS preview dock + native Wwise voice playback (eSpeak-NG / Piper)
  tts_engine.py                TTS synthesis engine
  speaker_map.py               Wwise voice-type → speaker (name/gender/faction) parser
  speaker_panel.py             Speaker (NPC) dock — who voices the selected line
  focus_overlay.py             Zen / full-screen focus mode
  lore_rag_manager.py          SQLite FTS5 lore database + UESP downloader
  lore_rag_dialog.py           Lore database management dialog
  quality_checker.py           Post-translation QA checks (20+ codes) and auto-fix
  quality_dialog.py            QA results dialog — filtering, per-code hide, auto-fix, retranslation
  ai_qc_worker.py              Worker thread for qcgemma4-st quality model
  spell_checker.py             Hunspell spell-check wrapper (3 backends: lib / spylls / CLI)
  font_checker_dialog.py       SWF/TTF glyph coverage checker dialog
  string_table.py              QAbstractTableModel for strings, ESP, and TXT modes
  term_protector.py            Placeholder-based term protection (8000+ terms)
  translation_cache.py         SHA-256-keyed persistent translation cache
  translation_memory.py        Pre-loaded map of string ID → known-good translation
  glossary.py                  Glossary data model, CSV/TBX/JSON I/O
  consistency_checker.py       Finds inconsistent translations of identical source strings
  gender_checker.py            Ukrainian adjective/noun gender agreement checker
  vmad_dialog.py               VMAD script-property analysis UI (risk-coloured, byte-splice apply)
  esp_migrate_dialog.py        ESP/ESM mod-update migration UI (FormID-keyed diff)
  version_compare_dialog.py    Game-version diff UI, migration, CSV/HTML export
  diff_viewer.py               Side-by-side word/character-level diff viewer
  pre_translation_estimator.py Difficulty scorer (0–100) with weight learning
  profile_editor_dialog.py     Character persona profile editor
  profile_assign_dialog.py     Assign persona profiles to strings / quests
  keyboard_manager.py          Rebindable shortcuts, vim navigation, command palette
  session_manager.py           Named work sessions with persistent search/filter state
  macro_recorder.py            Record/replay sequences of edit operations as macros
  theme_manager.py             16 built-in QSS themes + custom theme loader
  nexusmods_uploader.py        NexusMods v3 multipart upload client
  nexusmods_browser_dialog.py  NexusMods translation browser (card grid, async thumbnails)
  nexusmods_client.py          NexusMods REST v1 + GraphQL v2 API client
  app_settings.py              AppSettings dataclass, JSON + QSettings persistence
  secret_store.py              API key storage (keyring + AES-256-GCM fallback)
  audit_log.py                 Append-only security audit log (JSON-lines)
  updater.py                   GitHub release update check + welcome "What's New" changelog
  desktop_notify.py            Cross-platform batch-complete notifications (notify-send / tray)
  crash_recovery.py            Periodic auto-save and recovery dialog

data/
  fonts/                       Game fonts extracted from Starfield SWF assets
    RF_35_M.ttf                Cyrillic body font (UK locale, $MAIN_Font)
    RF_55_M.ttf                Cyrillic bold
    RF_55_SB.ttf               Cyrillic semi-bold
    NB_Architekt_Light.ttf     Latin body font (EN locale)
    NB_Architekt.ttf           Latin bold
  dialogue_bg_tile.png         50×50 noise tile from dialoguemenu.swf
  *_words.txt                  Word lists for source-language leak detection (12 languages)

scripts/
  apply_quality_fixes.py       CLI: apply auto-fixes from a JSON report to SST XML
  extract_sharegpt_dataset.py  Export EN→target string pairs as ShareGPT JSONL
  create_qc_dataset.py         Generate QC training dataset (14,928 examples, 16 issue codes)
  compile_translations.sh      Recompile .ts → .qm UI translation files
  fetch_dictionaries.py        Download Hunspell .aff/.dic dictionaries into dicts/ (Windows/macOS spell-check bundle)
  download_lang_dicts.py       Download word-frequency lists into data/ (source-language leak detection)
  extract_starfield_glossary.py Build starfield_glossary.json from string files

packaging/
  bethesda-strings-editor.desktop      Linux desktop entry (file associations)
  bethesda-strings-editor-mime.xml     MIME-type definitions for .strings/.esp/.ba2

---

UI translation

UI translations live in gui/translations/<locale>.ts. After editing any .ts file:

./scripts/compile_translations.sh

Supported locales: uk_UA, de_DE, fr_FR, es_ES, pl_PL, cs_CZ, ko_KR.

---

Tests

python -m pytest tests/

---

License

MIT — see LICENSE.