BG3 Mod Auto Translator is a lightweight Python-based tool that helps mod creators and translators translate Baldur’s Gate 3 mod text content effortlessly. Instead of manually copying every line into a translator, this utility uses the DeepL API to automate the process, ensuring more or less high-quality translations. It’s designed to preserve the original file structure and formatting, so all your HTML & XML tags and placeholders remain intact after translation. This means you can localize your mods for different languages in a fraction of the time, without worrying about broken tags or messed-up formatting.


Automatic XML Parsing
Automatically detects and extracts all <content> tags from your mod’s XML files for translation, so only the meaningful text is translated, and code structure is untouched.

Preserves Formatting
Protects in-text tags, placeholders, and special symbols during translation. This ensures things like game tags (e.g. [Tag] or <br>), HTML entities, and variables remain unaltered in the translated text.

Languages:
Supports translating into multiple languages, with automatic source language detection if needed.

User-Friendly GUI
Provides a simple graphical interface (no command-line needed). The GUI includes options to open files, select languages, start translation, and save results. A dark mode and light mode are available to suit your preference.

DeepL Integration
Uses the DeepL API for high-quality machine translation. The tool can recognize if you have a Free or Pro API account and will display your account type. It also keeps track of the characters translated.

Output Naming
Saves the translated file with a language prefix or tag, so you can easily identify which file is for which language. Your original file remains untouched, and the translated version is saved separately (e.g., EN_myMod.xml for an English translation).





Using BG3 Mod Auto Translator is straightforward. Follow these steps to translate a mod XML file:


Download
Get the BG3 Mod Auto Translator.exe file (no ZIP archive needed).

First start (creates config.json)
Double-click BG3 Mod Auto Translator.exe once; the program starts briefly, it generates a config.json in the same folder.

Add your DeepL API key
Open config.json, paste your key into the "deepl_api_key" field, and save the file.

Launch again
Re-open BG3 Mod Auto Translator.exe—you’re now ready to translate!

Open an XML File: Click the “📂 Open File” button at the top-left and browse to your mod’s XML file (usually a localization file that contains text in <content> tags).     Once loaded, the text from the file will appear in the left textbox of the window.

Select Languages:
Choose the source language and target language for translation. If you’re not sure of the source language, leave it as Auto (the tool will auto-detect it). Then pick your desired target language (for example, DE for German, FR for French, etc.) from the Target Language drop-down.

Auto Translate: Click the “🌐 Auto Translate” button. The tool will connect to DeepL and translate all extracted text. You’ll see the translated text appear in the right textbox. During this process, any XML tags or placeholders are protected, so they remain correctly placed in the output. A progress bar may indicate the translation progress if the file is large, and the status box will update with any messages (like errors or completion status).

Review (Optional): You can scroll through the original (left) and translated (right) text boxes to review the
translation. The formatting should mirror the original, just with
translated text.

Save the Translated File: Click the “💾 Save As” button. The tool will prompt you to save the translated content as a
new XML file. It will automatically suggest a file name with the target
language appended (for example, adding a language code or name). Choose a
location and save the file. This file is your translated mod XML, ready
to be used in-game or shared.

❓FAQ

Q: How do I get a DeepL API key?
A: You can obtain a DeepL API key by creating an account on the DeepL website. DeepL offers a Free API plan (with a monthly 500,000 character limit) as well as a Pro (paid) plan. Sign up for the developer API, and once your account is created, you’ll find your API authentication key in your DeepL account settings or email. Copy that key and paste it into the config.json file of this tool. (Make sure not to share your key publicly, as it’s tied to your DeepL usage.)

Q: What if I hit the character limit on the free API?
A: The DeepL API Free plan allows up to 500,000 characters per month for translation. If you hit this limit, the tool will be unable to translate further until the limit resets (the counter refreshes on DeepL’s side at the start of the next month) or until you upgrade your plan. BG3 Mod Auto Translator helps by tracking the number of characters you’ve translated and displaying your remaining quota at the bottom. If you’re consistently hitting the limit, consider upgrading to a DeepL API Pro plan, which offers a higher or unlimited character allowance for the month. Alternatively, you can wait until your free limit renews and then continue translating. The tool will handle the API responses for limit reached by showing an error message if DeepL refuses due to quota, so you won’t accidentally go over the limit silently.

Q: Does this tool modify my original files?
A: No, the original XML file you load is not modified. The content is loaded into the program and translated in-memory. When you save, you are prompted to save the translation as a new file (with a new name, usually including the language name or code). This way, your original mod file remains unchanged, and you get a separate translated file. Always keep backups of your original files, but the tool is designed to be non-destructive.

Q: What types of text will it translate or skip?
A: The tool specifically looks for text inside <content> tags in the XML, since Baldur’s Gate 3 localization files typically encapsulate translatable text in those tags. It will extract that text and send it for translation. It will skip empty content tags or any content that doesn’t need translation. Also, as a safety measure, it replaces certain placeholders or tags (e.g. things in square brackets like [PlayerName], or XML/HTML tags like < and >) with temporary tokens before sending to DeepL. This prevents the translator from garbling these special sequences. After translation, it restores the original placeholders in the text. The result is a translated text that should work seamlessly in-game, with all placeholders and formatting exactly where they should be.



These features are currently in development or planned for a future release:


Glossary Support (DeepL):
Optional integration of DeepL glossaries for advanced users. This feature will allow users to define and manage their own translation glossaries locally, enabling more consistent and accurate translations—especially important for game-specific terminology, character names, item names, and lore that DeepL might otherwise misinterpret. Each glossary will be editable from within the tool.(In the first version, glossaries will only be editable through the JSON files stored locally on your machine.)

Threaded Translation (Responsiveness):
Done... but extremely large XML structures can still freeze the GUI and will need further optimization.

Cleaner Codebase  (Enhanced Maintainability):
Optional adoption of the official deepl‑python package to achieve an impressively cleaner and more maintainable code structure.

(opt.) Improved UI for Easier Manual Translation Adjustments:
(Redesign?) and enhance the user interface to simplify manual edits of XML
translation files, making the structure more intuitive.