Overview

pdx-deepl is a tool to do incremental auto translation of mods for Paradox games using DeepL.

Contents

• How does it work?
• Manual and Machine translation
• Supported Games
  • Special Cases
• Configuration
  • Glossaries
  • Ignore Files
• Statistics
• Getting DeepL API access
• Usage
  • Usage Tip
• Issues with free DeepL API
• How To Build

Status

How does it work?

The tool will use a base language and check whether a localization key from the base language is either missing or outdated in other languages. If a key is missing or outdated, it will translate the base language localization and add the translation to the same file for another language. Also, the translation is marked with a checksum of the base language key so that in a second run pdx-deepl can check whether a key was updated.

Manual and Machine translation

Localizations that are generated by pdx-deepl will have a comment like this at the end:

 je_obj_magic_academy: "Magische Akademie bauen" #deepl:3993713733

This marks them as machine translated and pdx-deepl will update them when necessary.

All localizations without this comment at the end will be treated as manually translated and are not touched by pdx-deepl.

In this example the localization objective_magic_dominance_idle_header is assumed to be manually translated and will therefore be ignored by pdx-deepl.

 je_obj_magic_academy: "Magische Akademie bauen" #deepl:3993713733
 objective_magic_dominance_idle_header: "Setzen Sie Ihren Weg fort"

The system allows translators to touch up specific localizations which are then preserved in further handling.

Supported Games

• Victoria 3
• Crusader Kings 3
• Others may work but are untested

Special Cases

The translator automatically escapes localization tags.

The following formats are currently escaped:

Formatting

• Example: #bold Some Text#!
• Formatting like bold but also any other formatting is escaped
• Anything starting with a # directly followed by text and then a space is not translated
• Also ending of formatting #! is escaped so that it does not get changed

Functions

• Example: Country [Country.GetName]
• Functions like these are escaped
• Anything inside of [] is not translated

Text Icons

• Example: @innovation! Innovation
• Text Icons like these are escaped
• Anything inside of @! without spaces is not translated

References

• Example: some $another_loc_key$ text
• References like these are escaped
• Anything inside two $ is not translated

Line Breaks and Tabs

• Example: \tCountry\nNext Country
• Line Breaks and Tabs like these are not translated

Configuration

pdx-deepl translation needs to be configured with a translation-config.json. In this file, you can define which language should be used as a base for translations and also which languages should be generated.

In this example the english localization will be treated as the source of truth, and pdx-deepl will generate translations for german and french without glossaries.

{
  "base-language": "english",
  "target-languages": [
    {
      "name": "german"
    },
    {
      "name": "french"
    }
  ]
}

Glossaries

NOTE: Local glossaries are not supported!

Glossaries can be referenced using their id in the config file:

{
  "base-language": "english",
  "target-languages": [
    {
      "name": "german",
      "glossary": "your-glossary-id"
    }
  ]
}

How to use the DeepL API to create and manage glossaries is documented here:

• https://developers.deepl.com/docs/api-reference/glossaries

Ignoring Files

You are able to ignore localization files by adding them to the ignore list.

pdx-deepl will fully ignore files that are in this list and won't try to translate them.

The ignore list contains relative (from the localization root) paths of files that should not be translated:

{
  "base-language": "english",
  "target-languages": [
    {
      "name": "german"
    }
  ],
  "ignore-files": [
    "english/your_loc_file_l_english.yml",
    "english/sub_directory/your_other_loc_file_l_english.yml"
  ]
}

Statistics

When pdx-deepl is started with the -stats command it will produce statistics about file and character counts. These can be quite helpful in evaluating costs or the usage budget.

Statistics will look like this:

INFO 2025/05/02 01:12:49 API Type: free
INFO 2025/05/02 01:12:49 API Character Usage: 97919
INFO 2025/05/02 01:12:49 API Character Limit: 500000
INFO 2025/05/02 01:12:49 Target Language(s): german
INFO 2025/05/02 01:12:49 Base Language: english
INFO 2025/05/02 01:12:49 Localization Files: 62
INFO 2025/05/02 01:12:49 Localization Keys: 2456
INFO 2025/05/02 01:12:49 Total Characters: 159155

Getting DeepL API access

DeepL offers free and pro plans for translations. For trying out the tool, I recommend starting with a free account. But if your mod is big, it may make sense to look into the pro-plan.

DeepL Documentation

• https://www.deepl.com/en/translator
• https://support.deepl.com/hc/en-us/articles/360019358899-Accessing-DeepL-s-API
• https://support.deepl.com/hc/en-us/articles/360020695820-API-Key-for-DeepL-s-API

Usage

First download the latest release from the Releases page of the repository:

• https://github.com/kaiser-chris/pdx-deepl/releases

The ZIP may be marked as a Virus. This is a false positive!

If you do not trust this, then you can build it yourself.

Then you can run the application like this:

.\pdx-deepl.exe --localization="X:\path\to\localization\directory" --api-token="your token"

NOTE: This path is specifically to the localization folder in your mod

All start commands can be found in the help dialog. Help dialog (.\pdx-deepl.exe -h):

Usage of pdx-deepl:
  -api-token string
        Required: Deepl API Token
  -api-type string
        Optional: Whether to use free or paid Deepl API (default "free")
  -config string
        Optional: Path to translation config file (default "translation-config.json")
  -localization string
        Optional: Path to localization directory of your mod (default ".")
  -stats
        Optional: When set produces relevant statistics about the localization like the character count

Usage Tip

If you do not know how to open the command line on Windows:

• Open the folder containing the pdx-deepl.exe
• Click into the top address bar of the explorer
• Clear it
• Write cmd and press enter
• Now you should have a command line window open

Issues with free DeepL API

The current version has issues when it is used with the free DeepL API:

• You will get "too many requests" errors, and those are from rate limiting by the DeepL API. The free api has lower priority than the paid one
• The current implementation skips further loc keys in the same file when it encounters the issue. Since the whole thing is incremental, you have to rerun the application to generate more keys. For my german translation, I had to run it quite a lot of times, but I got it done in the end.
• There IS a monthly character limit of 500k for the free API, which may be an issue when translating a big mod. But running it on another developer's PC with a different account should enable generating more translations
• I recommend starting with one language instead of multiple

How To Build

First download and install the Go SDK:

• https://go.dev/doc/install

Next, open the project folder in a terminal (e.g. cmd) and run the following command:

go build

That is it. There should be an executable in the project folder now.