Translates Bethesda Game Studios plugin files (.esp/.esm/.esl) using bgs-translator/xtl. Creates translation projects, runs LLM batch translation, generates prompt previews, and exports SST/XML for xTranslator.
How this skill is triggered — by the user, by Claude, or both
Slash command
/bgs-modding-superpowers:using-bgs-translatorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
`bgs-translator` is the agent-driven translation pipeline for Bethesda plugin
bgs-translator is the agent-driven translation pipeline for Bethesda plugin
text. It reads plugin strings, builds AI translation batches with glossary and
protected-span handling, writes a project memory database, and exports SST/XML
dictionaries for xTranslator or ESP-ESM Translator to finalize.
The browser GUI is the only GUI surface. The agent should prefer xtl for work
it can do directly; use the GUI for human review, provider/key setup when the
user wants it, prompt preview, progress monitoring, and manual cleanup.
xtl is the CLI entry point. It is PyPI-distributed (bgs-translator package)
and is not bundled with this plugin; the vendored tree only carries
documentation and helper scripts. On a fresh machine xtl version will fail.
This is a long-tail install task that the agent owns, not the user. Do not ask the user to install Python or pipx by hand. Run the readback first; if it fails, route to the setup skill which performs the install and PATH-fix.
# Readback. Run this BEFORE any of the workflow examples below.
xtl version
If xtl version errors with "command not found" or "not recognized", switch to
setting-up-bgs-modding-environment (look at "Step 3A - Install or verify
xtl" — it owns pipx install bgs-translator==0.9.0rc1, the pipx PATH-warning
flow, and the post-install smoke). After install, return here and proceed.
For an already-installed xtl that is broken, stale, or behind a recent
release, switch to maintaining-modding-environments ("Translator CLI
maintenance" section).
The KB cache that xtl reads from is ~/.bgs-modding-superpowers/kb/packs,
unified with this plugin's bgs_kb_* MCP tools. If bgs_kb_status lists a pack
but xtl batch plan still produces a single-entry glossary subset, suspect a
stale legacy cache at %LOCALAPPDATA%/bgs-modding-superpowers/kb and surface it
to the user instead of accepting the poor glossary silently.
For RAG-quality translation against a game, the user needs the per-game pack
AND the corresponding localization pack (e.g. bgs-kb-starfield and
bgs-l10n-starfield-zhhans for Starfield Simplified Chinese). Setup skill
handles both. If only one is installed, surface the gap before running real
batches.
Human manuals, read these files and explain them to users who need GUI help:
tools/bgs-translator/USER-GUIDE.zh-cn.mdtools/bgs-translator/USER-GUIDE.en.mdThese files ship inside the materialized plugin tree under
tools/bgs-translator/ alongside scripts/restart-web-gui.ps1; they are
present in a fresh vendor-clone install.
Most translator tools focus on editing string tables. xtl builds a complete
LLM request for each batch:
{P0} and <Alias=...>.This is why the output can be more context-aware than plain string-table machine translation: the LLM receives the text plus the mod's purpose, game lore, record-type meaning, glossary, and placeholder rules in one request.
Never assume a shown command is the only valid shape. Examples below are templates. Before using an unfamiliar option, check the live CLI:
# Show all top-level xtl command groups.
xtl --help
# Show provider commands and accepted provider options.
xtl profile --help
xtl profile add --help
xtl profile edit --help
# Show project import/export options.
xtl project --help
xtl project init --help
xtl project export --help
# Show inspect, planning, run, status, and cancellation options.
xtl inspect --help
xtl batch plan --help
xtl batch run --help
xtl batch status --help
Provider --sdk-kind is not always openai-compat. Check xtl profile add --help for the currently supported values. At the time of this skill, the
code supports openai, anthropic, gemini, and openai-compat.
.esp, .esm, or .esl directly. xtl emits SST/XML only.xtl profile set-key
for hidden interactive input, or let the user enter the key in the browser GUI.behavior.prompt_preview_required=false
before dispatching.needs_review as real work, not as success. Either fix it or report it.Use this flow when the user wants the agent to run the translation process.
Verify the local CLI.
# Confirm the installed/current xtl can start and report capabilities.
xtl version
Inspect the plugin before creating a project.
# Example path only. Replace with the user's real ESP/ESM/ESL.
xtl inspect plugin "D:\path\to\Mod.esm"
If game detection is ambiguous, pass a real game value. Do not guess silently.
Check available options with xtl inspect plugin --help.
Create or refresh a project.
# Create project memory from the source plugin. Example target language: zh-cn.
xtl project init <project> --plugin "D:\path\to\Mod.esm" --target-lang zh-cn
Configure the provider if needed.
# Example: OpenAI-compatible provider. Check xtl profile add --help for all sdk kinds.
xtl profile add <profile> --sdk-kind openai-compat --base-url <api-root> --model <model> --api-key-env <ENV_NAME> --json-mode json_object
# Store the key with hidden input. Never put the real key in the command line.
xtl profile set-key <profile>
# Example advanced settings. Use xtl profile edit --help before changing these.
xtl profile edit <profile> --max-concurrency 8 --rate-limit-rpm 120 --rate-limit-tpm 90000
# Test the provider and then make it active.
xtl profile probe <profile>
xtl profile activate <profile>
set-key prompts with hidden input and writes translator/profiles/.env.
Never place a real key in a shell command, commit, log, or chat message.
Inspect project content.
# Get high-level counts by record signature.
xtl inspect signatures <project>
# Example: inspect 100 quest entries. Check xtl inspect entries --help for filters.
xtl inspect entries <project> --sig QUST --limit 100
Research context before planning. For real mods, gather:
Plan the batch. For "all currently untranslated" use filters; for GUI
queue/fanatic mode use --queue <queue_id> when the user submitted one.
# Example: plan untranslated QUST text in groups of 200.
# This only writes plan.json and does not call the provider.
xtl batch plan <project> --register dialogue --target-lang zh-cn --profile <profile> --batch-size 200 --sig QUST --game-lore-world "Starfield 2330 Settled Systems" --game-lore-summary "<detailed lore>" --mod-name "<mod name>" --mod-theme "<detailed mod context>" --style "Polished Simplified Chinese game localization."
--register, --sig, --field, batch size, and context fields are examples.
Check xtl batch plan --help and inspect project signatures before choosing.
Report plan_id, total_items, batch_count, skipped_reasons, and the
plan path.
Dispatch the run.
# Start a background worker and return immediately with run_id and log paths.
xtl batch run <project> --plan <plan_id>
xtl batch run returns immediately by default. Use --wait only for tests or
deliberate foreground execution. Use --dry-run only for smoke tests. For
no-human-preview agent runs, first confirm:
# Disable required browser prompt preview only when the user asked for agent-only execution.
xtl config set behavior.prompt_preview_required false
Poll status and logs.
# Poll periodically after background launch.
Start-Sleep -Seconds 10
xtl batch status <run_id>
# Inspect recent persisted run files/logs if progress looks stuck.
xtl batch logs <run_id>
# Request cancellation if the user asks to stop.
xtl batch cancel <run_id>
Validate and export.
# Validate project state before export.
xtl validate project <project>
# Export xTranslator dictionary output.
xtl project export <project> --format sst
Tell the user which SST/XML files were emitted and that xTranslator/ESP-ESM Translator owns the final "Finalize" step.
Use this when the user wants the agent to prepare xTranslator finalization but
accepts that a human must click through xTranslator. The human's job is only:
launch xTranslator through MO2 when needed, open Wizards -> Batch Processor,
paste the script provided by the agent, run it, then copy the bottom Log tab
back to the agent. The agent must inspect the log for every StartRule:
Loading Esp/esm/esl file... succeeds for the intended file.Applying sstRessources... and importing/applying vocabfile run.Saving Esp/Esm/Esl files... or Saving Strings files... appears.BatchProcessor: Error line appears.- SC output, not the source mod unless a
deliberate loose-strings staging fallback was used.xTranslator's command line cannot run this workflow headlessly. It can load one file, but SST import/finalize is driven by Batch Processor text.
Before generating any Batch Processor script, create or verify the corresponding
MO2 output mod folder under ...\MO2\mods\ using the source mod's name plus
- SC, for example D:\Starfield MO2\mods\Some Mod - SC. This folder is the
only intended landing place for finalized translation files. Do not let
xTranslator save final deliverables into the source mod unless using the
temporary loose-strings staging fallback described below.
# Create the sibling MO2 mod that will receive finalized Chinese output.
New-Item -ItemType Directory -Force -Path "D:\Starfield MO2\mods\Some Mod - SC" | Out-Null
Generate one StartRule block per plugin. Use full Windows paths. Keep path
arguments unquoted inside the Batch Processor block; xTranslator reads the rest
of the line after the command prefix, so spaces are valid there.
Important commands:
LangSource=en and LangDest=zhhans select the language pair.UseDataDir=false tells xTranslator to use the explicit file path instead of
the game Data folder.Command=LoadFile:<plugin> loads one .esm/.esp/.esl.Command=ImportSst:<applyOn>:<mode>:<sst> imports an SST dictionary.Command=Finalize writes the final output for the loaded file.Command=CloseFile closes it before the next rule.Useful ImportSst parameters:
applyOn=0: apply to everything.applyOn=1: apply only to not-translated items.mode=1: strict FormID + original string matching.mode=3: strings-only matching.Preferred pattern: run strict first, then optionally use strings-only only for still-untranslated items:
Command=ImportSst:0:1:C:\path\to\project\exports\mod_english_chinese.sst
Command=ImportSst:1:3:C:\path\to\project\exports\mod_english_chinese.sst
If the user is debugging record identity, omit the strings-only fallback so unmatched records remain visible.
Use this for mods where xTranslator saves the plugin itself, such as a compact
ESM/ESP/ESL workflow. Do not load the source plugin. First copy the source
plugin to the sibling MO2 overlay directory named Original Mod Name - SC, then
load that copied file in Batch Processor.
# Prepare the sibling MO2 overlay so xTranslator finalizes a copy, not the source plugin.
New-Item -ItemType Directory -Force -Path "D:\path\to\Mod Name - SC" | Out-Null
Copy-Item -LiteralPath "D:\path\to\Mod Name\mod.esm" -Destination "D:\path\to\Mod Name - SC\mod.esm" -Force
Then provide the human this Batch Processor block:
StartRule
LangSource=en
LangDest=zhhans
UseDataDir=false
Command=LoadFile:D:\path\to\Mod Name - SC\mod.esm
Command=ImportSst:0:1:C:\path\to\project\exports\mod_english_chinese.sst
Command=ImportSst:1:3:C:\path\to\project\exports\mod_english_chinese.sst
Command=Finalize
Command=CloseFile
EndRule
Expected success log contains Saving Esp/Esm/Esl files... and a saved path
under Mod Name - SC.
Use this for string-backed Starfield plugins where xTranslator finalizes
strings\*_zhhans.strings, *.dlstrings, and *.ilstrings instead of changing
the BA2. Preferred: copy the plugin and text BA2 to - SC, load the copied
plugin there, and let xTranslator write loose strings directly under - SC.
# Prepare a sibling overlay with the plugin and the BA2 that contains source strings.
New-Item -ItemType Directory -Force -Path "D:\path\to\Mod Name - SC" | Out-Null
Copy-Item -LiteralPath "D:\path\to\Mod Name\mod.esm" -Destination "D:\path\to\Mod Name - SC\mod.esm" -Force
Copy-Item -LiteralPath "D:\path\to\Mod Name\mod - main.ba2" -Destination "D:\path\to\Mod Name - SC\mod - main.ba2" -Force
Batch Processor block:
StartRule
LangSource=en
LangDest=zhhans
UseDataDir=false
Command=LoadFile:D:\path\to\Mod Name - SC\mod.esm
Command=ImportSst:0:1:C:\path\to\project\exports\mod_english_chinese.sst
Command=ImportSst:1:3:C:\path\to\project\exports\mod_english_chinese.sst
Command=Finalize
Command=CloseFile
EndRule
Expected success log contains Saving Strings files... and saved files under
Mod Name - SC\strings\.
After verifying the target-language loose files exist under Mod Name - SC\strings\, delete the temporary copied plugin/archive files from Mod Name - SC. For string-localized mods, the delivered MO2 overlay only needs the loose
strings\*_zhhans.strings, *.dlstrings, and *.ilstrings files; keeping the
copied .esm/.esp/.esl, .ba2, or .bsa in - SC can shadow the source mod
unnecessarily.
# After successful string finalization, keep only the loose translated strings.
Remove-Item -LiteralPath "D:\path\to\Mod Name - SC\mod.esm" -Force
Remove-Item -LiteralPath "D:\path\to\Mod Name - SC\mod - main.ba2" -Force
If the BA2 is too large to copy and the user accepts a staging step, load the
source plugin and let xTranslator write loose target-language strings into the
source mod's strings folder. Immediately move only the generated target
language files to - SC\strings:
# Move the loose target-language strings produced by xTranslator into the sibling overlay.
New-Item -ItemType Directory -Force -Path "D:\path\to\Mod Name - SC\strings" | Out-Null
Move-Item -LiteralPath "D:\path\to\Mod Name\strings\mod_zhhans.strings" -Destination "D:\path\to\Mod Name - SC\strings\mod_zhhans.strings" -Force
Move-Item -LiteralPath "D:\path\to\Mod Name\strings\mod_zhhans.dlstrings" -Destination "D:\path\to\Mod Name - SC\strings\mod_zhhans.dlstrings" -Force
Move-Item -LiteralPath "D:\path\to\Mod Name\strings\mod_zhhans.ilstrings" -Destination "D:\path\to\Mod Name - SC\strings\mod_zhhans.ilstrings" -Force
Only use this fallback when the user explicitly accepts temporary writes to the source mod directory. Never write into the game Stock/Data directory.
Use the GUI when a human needs to configure, inspect, approve, or manually fix:
# Launch the local browser control panel.
xtl gui
If the GUI or its process state becomes inconsistent, restart it with the stable helper:
# From tools/bgs-translator, restart the web GUI on the usual local port.
powershell -ExecutionPolicy Bypass -File .\scripts\restart-web-gui.ps1 -Port 7847
The GUI is browser-only. There is no Tk fallback.
High-signal tabs:
For detailed player-facing guidance, point the user to the manuals listed at the top of this skill.
For maintaining Starfield official terminology packs, mod-specific glossary
packs, or third-party Skyrim/Fallout localization KBs, switch to
maintaining-modding-environments. Translator runs consume those packs; they do
not own KB release or provenance policy.
Do not send generic prompts. For every real batch, build context with:
{P0} and <Alias=...>.If the user provides a mod URL, browse it and summarize relevant features. If the mod page is unavailable, use local readmes/project entries and state the gap.
Align user-facing status with xTranslator concepts:
untranslated: no accepted translation exists.translated: validated/accepted translation.needs_review: partial or suspicious translation that requires human review.locked: should remain unchanged and should not be sent to AI.Placeholder-only and number-only strings should not enter AI batches. Do not hide a mismatch between GUI counts and exported SST; investigate before claiming success.
--help for supported values first.npx claudepluginhub bb-84c/bgs-modding-superpowers --plugin bgs-modding-superpowersProvides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.