using-bgs-translator
Use when the user wants to translate a Bethesda Game Studios plugin (.esp/.esm/.esl) with bgs-translator/xtl, create or inspect a translation project, run LLM batch translation, generate prompt previews, or export SST/XML for xTranslator.
Install / Use
npx skills add hashgraph-online/awesome-codex-plugins --skill using-bgs-translatorInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Our assessment of using-bgs-translator
using-bgs-translator scores 93/100 on our quality scale, 714th of 2,790 Automation skills we index (top 26%).
Its SKILL.md is 25 KB long, well organised into 30 sections with 14 code examples: a thorough specification that gives an agent plenty to work with.
With 1,075 GitHub stars, it is one of the more widely adopted skills in the catalogue.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so using-bgs-translator is actively maintained.
- Our last check on 2026-10-25 found the source still online.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
No issues foundOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
using-bgs-translator compared with similar skills
All 4 of these similar skills score higher than using-bgs-translator; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| using-bgs-translator (this skill)by hashgraph-online | 93 | 1.1k | 53d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 39.7k | 7d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 103.6k | 2d ago | MCP Server |
Frequently asked questions
- How do I install using-bgs-translator?
- Run
npx skills add hashgraph-online/awesome-codex-plugins --skill using-bgs-translator. The install tabs above show the steps for each supported agent. - Which AI agents does using-bgs-translator work with?
- It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is using-bgs-translator safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is using-bgs-translator still maintained?
- The repository was last updated about 2 months ago, so using-bgs-translator is actively maintained.
Skill content
View source on GitHubname: using-bgs-translator description: Use when the user wants to translate a Bethesda Game Studios plugin (.esp/.esm/.esl) with bgs-translator/xtl, create or inspect a translation project, run LLM batch translation, generate prompt previews, or export SST/XML for xTranslator. Triggers - "translate this mod", "汉化这个 mod", "localize plugin", "build SST", "use xtl", "bgs-translator".
Using bgs-translator
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.
Prerequisites — verify before any other command
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:
- Chinese:
tools/bgs-translator/USER-GUIDE.zh-cn.md - English:
tools/bgs-translator/USER-GUIDE.en.md
These 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.
本地化判断 / Localization judgment
Localization is not "send every string to a provider." It is the curator's job to decide which player-visible text should change, which technical spans must stay exact, and which terms must remain consistent across the whole pack. A translation tool can produce candidate text; it cannot decide the pack glossary, the winning string provider, or whether a string is actually safe to edit.
The core mechanic is the runtime string chain: the player sees the value from the plugin/patch layer that wins at runtime. A base-game translation or an older mod translation can be overridden by a later mod, update patch, or compatibility patch. Do not treat missing Chinese as a mysterious tool failure. First identify the winning string provider, then localize that layer.
Source basis: BB84's FO4 localization 疑难杂症 transcript ([E8] in
.opencode/artifacts/sixiang-build/injection-using-bgs-translator/framework-extraction.md)
explains the override chain, attribution workflow, patch-localization ordering,
and non-translatable/signature caveats. That extraction also marks current
[GAP] items; do not fill those gaps from guesswork.
digraph localization_judgment {
rankdir=TB;
node [shape=box];
start [shape=doublecircle, label="String candidate"];
visible [shape=diamond, label="Player-visible text?\n(dialogue, quest, item name, book, UI, MCM, loading screen)"];
protected [shape=diamond, label="Protected span or internal reference?\nplaceholder, EditorID, script key, FormID, path, token"];
kb [label="Query KB for this game's protected signatures/fields\nand localization gotchas"];
winning [label="Find the winning runtime provider\nbase mod? update patch? compatibility patch? loose text file?"];
glossary [shape=diamond, label="Term already locked by pack glossary?"];
translate [label="Translate/reuse comparison translation\nwhile preserving protected spans"];
normalize [label="Normalize to pack glossary\nor record a deliberate term change"];
review [label="Sample readback in context\nneeds_review is real work"];
lock [shape=doublecircle, label="LOCK / do not translate"];
skip [shape=doublecircle, label="SKIP / not a localization target"];
done [shape=doublecircle, label="ACCEPT localized string"];
start -> visible;
visible -> skip [label="no"];
visible -> protected [label="yes"];
protected -> lock [label="yes"];
protected -> kb [label="unclear / no"];
kb -> winning -> glossary;
glossary -> normalize [label="yes, differs"];
glossary -> translate [label="no / already matches"];
normalize -> review;
translate -> review;
review -> done [label="context and placeholders pass"];
review -> translate [label="mismatch"];
}
Protected-span red flags
Never localize a span just because it appears in an extracted text table. The safe default is: player-facing prose can be translated; identifiers and engine references stay exact unless the per-game KB or the tool's schema proves they are display values.
| Red flag | What to do instead |
|---|---|
| Placeholder, formatter token, alias marker, or bracket tag appears inside the text. | Preserve it byte-for-byte and translate only the surrounding prose. |
| The value looks like an EditorID, script property, config key, JSON key, file path, plugin name, FormID, or hex ID. | Lock it unless KB/tool docs identify it as display text. |
| A record/signature/field type is unfamiliar. | Query KB for the current game before translating; if KB is silent, mark [GAP] and review manually. |
| Generated naming-rule or FormID-dependent text is selected for comparison/bulk translation. | Do not bulk-translate. Use manual semantic review or leave locked until KB confirms the safe handling. |
| A translated plugin is being sorted after update/compatibility patches to "win" text. | Do not break the functional patch layer. Localize the patch that actually wins, then load that localized patch after the functional layer. |
Rationalizations
| Excuse | Reality | |---|---| | "There must be a universal localization patch." | There is no final patch that covers every later mod-side string. Find the winning provider. | | "The base-game Chinese patch is installed, so English text means the translator failed." | A later mod or patch may be overriding the localized base string. Attribute first. | | "Just translate everything; the validator will catch problems." | Validators catch known placeholders, not every engine reference, naming-rule dependency, or glossary drift. | | "The old Chinese ESP worked before; put it at the end." | That can invalidate update/compatibility patches, and stale translations may miss new records. Regenerate against the current winning layer. | | "Different mods can translate the same term differently; players will understand." | A pack needs one glossary. A later competing term is a judgment call, not accidental drift. |
KB query discipline
This section is game-agnostic. Do not fossilize FO4, Skyrim, or Starfield protected-string lists in this skill. Before a real batch, query KB for the current game and mod shape:
bgs_kb_query({
query: "localization protected strings placeholders EditorID FormID generated names",
domains: ["install-planning", "plugin-format"],
games: ["<current game>"]
})
bgs_kb_query({
query: "translation glossary consistency string lookup override chain",
domains: ["install-planning", "load-order"],
games: ["<current game>"]
})
If KB is silent for a protected-string category, write [GAP] in the plan and
keep the string out of unattended AI translation. Per-game protected-string and
FormID-dependency patterns belong in KB records, not in this skill body.
What xtl Does Better
Most translator tools focus on editing string tables. xtl builds a complete
LLM request for each batch:
- It extracts only translatable plugin text into project memory.
- It masks dangerous placeholders such as
{P0}and<Alias=...>. - It deduplicates repeated text where safe.
- It recalls relevant game/mod/player terminology.
- It adds game context, mod context, signature explanations, style rules, and do-not-translate rules to a system prompt.
- It sends compact JSON-shaped work items to the selected provider.
- It validates the response before writing translations back to project memory.
- It exports SST/XML for xTranslator instead of editing the original plugin.
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.
Help and Capability Discovery
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.
Operating Rules
- Do not edit
.esp,.esm, or.esldirectly.xtlemits SST/XML only. - Do not route translator work through xEdit or MO2 unless the user explicitly asks for an unrelated xEdit/MO2 task.
- Do not accept API keys in chat or command history. Use
xtl profile set-keyfor hidden interactive input, or let the user enter the key in the browser GUI. - Do not bypass prompt preview when the user has enabled it. If the user asks for
a fully agent-run batch, set/confirm
behavior.prompt_preview_required=falsebefore dispatching. - Always surface plan size, batch count, skipped placeholder-only count, and the output dictionary path.
- Treat
needs_reviewas real work, not as success. Either fix it or report it.
CLI End-to-End Flow
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 mem
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
39.7kTurn Claude Code into a full game dev studio — 49 AI agents, 72 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
103.6k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
