Metadata-Version: 2.4
Name: bgs-translator
Version: 0.9.0rc1
Summary: LLM-assisted Bethesda Game Studios plugin translation pipeline for xTranslator and ESP-ESM Translator.
Author: BB-84C
License-Expression: MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.15
Requires-Dist: pydantic>=2.10
Requires-Dist: httpx>=0.27
Requires-Dist: tomli-w>=1.0
Requires-Dist: pyyaml>=6
Requires-Dist: python-dotenv>=1.0
Requires-Dist: openai>=1.50
Requires-Dist: anthropic>=0.40
Requires-Dist: google-genai>=0.5
Requires-Dist: nicegui<4.0,>=3.12.1
Requires-Dist: uvicorn>=0.30
Requires-Dist: watchdog>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: playwright>=1.45; extra == "dev"
Requires-Dist: pytest-playwright>=0.5; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: types-PyYAML>=6; extra == "dev"

# bgs-translator

`bgs-translator` is an LLM-driven sister tool for xTranslator and ESP-ESM Translator. It reads Bethesda plugin translatable strings, runs them through an LLM batch pipeline with glossary and protected-span handling, and emits `.sst` files (or ESP-ESM XML for TES3/Morrowind) that the downstream translator GUI can finalize.

## Install

Published package, once available:

```powershell
pipx install bgs-translator
```

Development checkout:

```powershell
cd D:\awesome-bgs-mod-master\tools\bgs-translator
pipx install -e .
```

Confirm the install:

```powershell
xtl version
```

## Quick start

This sequence creates a small project, plans one LLM batch, rehearses the run, and exports SST output:

```powershell
$env:BGS_MODDING_SUPERPOWERS_HOME = "$env:TEMP\bgs-translator-demo"

xtl project init demo-mod --plugin "D:\path\to\MyMod.esp" --game SkyrimSE --target-lang zh-cn

xtl batch plan demo-mod `
  --register names `
  --target-lang zh-cn `
  --profile my-openrouter-profile `
  --sig WEAP `
  --field FULL `
  --game-lore "Skyrim fantasy setting" `
  --mod-name "MyMod" `
  --mod-theme "Adds a small set of weapons." `
  --style "Concise Simplified Chinese item names."

xtl batch run demo-mod --plan <plan_id> --dry-run --wait
xtl project export demo-mod --format sst
```

Open the emitted SST file in xTranslator or ESP-ESM Translator, review, then use that GUI's Finalize workflow to produce the game-ready translation files.

## Commands

Run `xtl --help` or any subcommand's `--help` for the current option surface.

- `xtl version` — JSON envelope with version and capability flags.
- `xtl config ...` — global settings, resolved paths, and KB cache migration.
- `xtl profile ...` — provider profiles by environment-variable key reference.
- `xtl project init|export` — project creation and dictionary export.
- `xtl inspect plugin|signatures|entries|entry|orphans` — parser and memory inspection.
- `xtl batch plan|run|status|cancel|logs` — batch planning, execution, status, cancellation, and logs.
- `xtl edit entry|bulk|status|revert` — manual translation-memory edits.
- `xtl validate project|sst` — project and SST validation.
- `xtl gui` — browser control panel.

## GUI

Launch the browser control panel with:

```powershell
xtl gui
```

The panel is for configuration and monitoring: AI service accounts, prompt preview, batch progress, cancellation, glossary controls, and export checks. It uses the amber/green/mono terminal theme in a local browser page. Billing is not estimated in the GUI; use the provider dashboard for real usage and cost.

`xtl batch run` starts a background worker and returns a `run_id` immediately.
Poll with `xtl batch status <run_id>`, or pass `--wait` for foreground smoke tests.

For local development, restart the browser GUI with the reusable PowerShell harness. It stops the stale GUI PID or port owner, starts the correct web module entry point, and waits for `/healthz`:

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\restart-web-gui.ps1 -Port 7847
```

The browser panel is the only supported GUI:

```powershell
xtl gui
```

## Documentation

User guides:

```text
D:\awesome-bgs-mod-master\tools\bgs-translator\USER-GUIDE.zh-cn.md
D:\awesome-bgs-mod-master\tools\bgs-translator\USER-GUIDE.en.md
```

The product requirements and chunk plans live in:

```text
D:\awesome-bgs-mod-master\docs\plans\translator-tool\
```

Start with `00-overview.md`; `AMENDMENTS.md` overrides earlier PRD notes where implementation spikes found corrections.

## Status

Alpha / release-candidate state. It is ship-ready for personal use and integration testing, with community contribution welcome before a wider v1.0 release.

Known release gates include bgs-kb localization pack publishing, manual xTranslator GUI verification, and continued hardening around Morrowind ESP-ESM XML interoperability.

## License

MIT. Authored by BB-84C as part of `bgs-modding-superpowers`.
