[GUI Plugin] Ebook Translator

[kindlefere]

Ebook Translator is a Calibre plugin to translate your ebook into a specified language (optionally keeping the original content).

When reading a foreign ebook/document/file, it can be frustrating to switch back and forth between a translation tool and the reading material. Ebook Translator offers a convenient solution to obtain all translated text, with or without original paragraph, in a single click. This can be a good assistant for reading and translation work.

With the huge ebook formats supported by Calibre, and the huge number of languages supported by translation engines, we can put almost any ebook format to translate and output as any format we like. For example, you can put TXT and get TXT/EPUB translation, or put PDF and get PDF/DOCX translation.

Here is what a translated ebook looks like:



Features

• Support languages supported by the selected translation engine (e.g. Google Translate supports 134 languages)
• Support multiple translation engines, including Google Translate, ChatGPT, and DeepL
• Support custom translation engine (you can configure to parse response in JSON or XML format)
• Support all ebook formats supported by Calibre (48 input formats, 20 output formats)
• Support to translate more than one ebooks, the translation process of each book is carried out simultaneously without affecting one another
• Support caching translated content, no need to re-translate after request failure or network interruption
• Provide a large number of customization settings, such as saving translated ebooks to Calibre library or designated location

Installation

Please make sure Calibre is installed on your OS, and install the plugin via either ways below:

[Install from Calibre]

1. Click Calibre Menu [Preference... -> Plug-ins -> Get new plugins].
2. Select Ebook Translator from the plugin list, and click [Install].
3. Reboot Calibre.

[Load from file]

1. Download the plugin zip file from Github or attachment of this post.
2. Click Calibre Menu [Preference... -> Plug-ins -> Load plug-in from file], and choose the zip file you downloaded.
3. Reboot Calibre.

* If the "Translate Book" plugin is not showing up on Calibre menu, you need to add it from [Preference... -> Toolbars & menus], choose [The main toolbar], find the plugin and click ->, and [Apply]).

Usage

1. Select the ebook(s), and click the plugin icon "Translate Book"
2. Select the Target Language (and Output Format if needed)
3. Click [TRANSLATE]



After that, you can check the translation process by clicking "Jobs" at the bottom right. Double clicking the job item, you can check the real-time translation log from the window it prompts.



Settings

Ebook Translator offers plenty of customization settings. You can choose from "Content" and "Setting" panel as needed:

Spoiler:

Content

[Translation Position]

• Add after original [default]: Add the translation text after original text
• Add before original: Add the translation text before original text
• Add without original: Add the translation text and delete original text

[Translation Color]

• Color Value: CSS color value, e.g., #666666, grey, rgb(80, 80, 80)

You can click the [Select] button to select a color from color palette, or enter the color value manually. Please refer to "color value" on MDN documentation for details. If left blank no customized color will be applied.

[Merge to Translate]

• Enable [default unchecked]: Enable to merge to translate

You can specify the number of characters to translate at one time, default value is 2000.

[Translation Glossary]

• Enable [default unchecked]: Enable to use the selected translation glossary file

A translation glossary serves to define precise translations for particular terms and to direct the translation engine to exclude specific terms from translation.

The glossary file is a plain text file with extension .txt. It has the following format: if a term requires a specific translation, it is presented as a pair of two lines, the first one with the original term and the second one with its translation; If a term needs to be ignored in translation, it is presented as a single line per term. The groups of terms are separated by a blank line.

La Torre Eiffel
The Eiffel Tower

La Estatua de la Libertad

[Do not Translate]

• Normal [default]: Exclude paragraph by keyword (one keyword per line)
• Normal (case-sensitive): Exclude paragraph by case-sensitive keyword (one keyword per line)
• Regular Expression: Exclude paragraph by Regular Expression rule (one rule per line)

For regular expression syntax, please refer to "Regular Expression Syntax" on Python documentation.

Setting

[Output Path]

• Library [default]: After the ebook is translated, it will be placed in Calibre library
• Path: After the ebook is translated, it will be stored in specified directory

[Translation Engine]

• Google [default]: Free translation engine
• ChatGPT: API key required
• DeepL: API key required
• DeepL(Pro): API key required
• Youdao: APP key and secret required
• Baidu: APP id and key required
• Custom: Customize your own translation engine

Except for Google, who does not require an API key, other translation engines require you to register a corresponding account and pay to obtain an API key.

If you opt for a paid translation engine, we recommend you to refer to its official documentation for pricing rules. For example, ChatGPT uses its official tool, Tokenizer, to estimate the number of tokens required to translate a given amount of text in order to provide a cost estimate.

You can click the [Test] button to test the selected translation engine. If translation engine provides quota information, it will be displayed at the bottom of Translation Engine Tester window.

Click the [Custom] button, you will enter the "Custom Translation Engine" interface, where you can add, delete and configure a translation engine.

The data to configure a custom translation engine is in JSON format. Each time you add a new custom translation engine, a data template, as shown below, will be displayed for your reference:

{
    "name": "New Engine - 36e05",
    "languages": {
        "source": {
            "Source Language": "code"
        },
        "target": {
            "Target Language": "code"
        }
    },
    "request": {
        "url": "https://example.api",
        "method": "POST",
        "headers": {
            "Content-Type": "application/json"
        },
        "data": {
            "source": "<source>",
            "target": "<target>",
            "text": "<text>"
        }
    },
    "response": "response"
}

The above data template contains 4 name/value pairs, which will be explained below. You can update the template as needed.

• name: The name of the translation engine displayed on the UI, for example, Bing.
• languages: The language codes supported by the translation engine. The format is {'Language Name': 'language code'}. Please refer to the documentation of the translation engine API for details. You can also specify the source language and target language respectively.
  • source: The source language. The format is the same as for languages.
  • target: The target language. The format is the same as for languages.
• request: Request data, including the following name/value pairs:
  • url: The API URL, as specified in the documentation of the translation engine API.
  • method: The request method (optional), with a default value of GET.
  • headers: The request header (optional). You can refer to the documentation of the translation engine API for details.
  • data: Request data, can be either a dict object which will be encoded and sent as application/x-www-form-urlencoded data or a string which will be sent as is. If you use a string you should also set the Content-Type header appropriately. It includes 3 built-in variables: <source>, <target>, and <text>. <source> and <target> correspond to the language codes set earlier, and can be ignored if not needed; <text> refers to the original text sent to the translation engine, which must be included to save. Please refer to the documentation of the translation engine API for details.
• response: The expression used to parse the response data to obtain the translation text. The response data is included in the response variable, which is a JSON object (if the response from the translation engine is in JSON format) or an Element object of lxml (if the response from the translation engine is in XML format).

Once you have completed the data for the custom translation engine, you can click the [Verify] button to check whether the data format is valid, and click the [Save] button to save all the changes.

[ChatGPT Prompt]

• For auto detecting source language: Customize ChatGPT prompt to translate from 'Auto detect' source language
• For specifying source language: Customize ChatGPT prompt to translate from specified source language

[Preferred Language]

• Target Language [default UI language]：Set the preferred target language.

[Network Proxy]

• Enable [default unchecked]: Enable network proxy
• Host: Support IP and domain name
• Port: Range 0-65536
• Test: Test the connectivity of proxy

[Cache]

• Enable [default checked]: Enable to cache translated content
• Clear: Delete all caches

Enabling the caching function can avoid re-translation of the translated content after request failure or network interruption. You can also check the amount of disk space occupied by the cache here, and click [Clear] button to delete all caches. Note that if a translation job is currently in progress, the [Clear] button will be disabled to use.

[Request]

• Attempt Times [default 3]: The number of times to attempt if the request to translation engine fails
• Maximum Interval [default 5 seconds]: The maximum time interval to request translation engine

A single request to translation engine can last up to 300 seconds. After the timeout, it will retry according to the specified attempt times, and the waiting time for each retry will be gradually increased. The request interval will be a random number between 1 and the maximum interval specified.

When using Google Translate API, which is currently available for free, we recommend you to increase the "Maximum Interval" to an appropriate value (more than 5 seconds is recommended) to prevent it from being flagged as abusive behavior, which could lead to translation interruptions or denial of service. For paid translation engines, the "Maximum Interval" can be set to 1.

[Log]

• Display translation [Default checked]: The translation content will be displayed in real time from the respective log window of the translation job

[Zetmolm]

Great idea. This would be very helpful for reading books in a foreign language. But there is still quite some work to be done, I'm afraid. I tried this on 3 or 4 books (epub and fb2 formats). Either only some headers in the book were translated, or the process ended in an error.
Please keep up the good work! I'll try again when there is a new release.

[kindlefere]

Thanks for your try. We will work on the issue on fb2 format.

For the error, is it something like "<urlopen error [Errno 54] Connection reset by peer>"? (You can check the error message from: "Jobs" link on Calibre at bottom right - double click the job item - drag to the bottom of prompt log window.)

If yes, it is the connection issue of translation engine. You can increase the number of [Maximum interval] from setting interface and [Save] to try again.

[Zetmolm]

Thanks for the feedback. I'll play around with the settings and see if it helps.

Note that I did not just have problems with fb2, but also for a few epubs I had this issue that only a few headers were translated and no body text. After conversion epub --> epub in Calibre the problem still occurred. I then converted one of these epubs to txt and started translation of that version. Translation is currently in progress, but now I see in "Jobs" under Status that 4590 units are being translated instead of only 7. So it seems that something goes wrong when the translator tries to parse the epub, or something in the epub prevents proper parsing, whichever way you want to look at it.

[kindlefere]

ok, observation noted. The problem is currently only certain tags are chosen for content to be translated. For books with content in other tags, this will not work.

We will figure out a way to handle different structure of various books. Thanks for your concern.

[Zetmolm]

Thanks!

The translation of the txt book completed successfully. Now I'm doing some simple formatting to make it into a more or less decent epub.

I understand that epub and fb2 are not fully supported yet. Are there any other formats (besides txt) that currently are fully supported?

Looking forward to new and improved releases!

[Sunlite]

This is a really great idea. I have tried it out with one short story and it works!

There are some things I would wish for /find helpful:

- add the new book to thelibrary as a new book instead of overwriting the original
- set a language attribute at each paragraph
- be able to switch the order of translated and original paragraph

Thank you for your work.

[kindlefere]

Originally Posted by Zetmolm

Thanks!

The translation of the txt book completed successfully. Now I'm doing some simple formatting to make it into a more or less decent epub.

I understand that epub and fb2 are not fully supported yet. Are there any other formats (besides txt) that currently are fully supported?

Looking forward to new and improved releases!

Other formats may have the same issue as epub & fb2, for their xhtml tags of book content are not quite the same. It actually depends on the book you use.

[kindlefere]

Originally Posted by Sunlite

This is a really great idea. I have tried it out with one short story and it works!

There are some things I would wish for /find helpful:

- add the new book to thelibrary as a new book instead of overwriting the original
- set a language attribute at each paragraph
- be able to switch the order of translated and original paragraph

Thank you for your work.

Thanks for your insight. All three suggestions are very helpful! We will work on it.

[Zetmolm]

I got a few books translated successfully. But for several books translation ran for several hours, and then, when all units had been translated, I got a FileNotFoundError error, e.g. like the following. No translated book was created. Is there something I can do about this?

Spoiler:

....
Parsing all content...
Merging user specified metadata...
Detecting structure...
Flattening CSS and remapping font sizes...
Source base font size is 12.00000pt
Removing fake margins...
Cleaning up manifest...
Trimming unused files from manifest...
Creating EPUB Output...
translating ebook content ... (this will take a while)
Traceback (most recent call last):
File "runpy.py", line 196, in _run_module_as_main
File "runpy.py", line 86, in _run_code
File "site.py", line 83, in <module>
File "site.py", line 78, in main
File "site.py", line 50, in run_entry_point
File "calibre\utils\ipc\worker.py", line 215, in main
File "calibre\utils\ipc\worker.py", line 150, in arbitrary_n
File "calibre_plugins.ebook_translator.convertion", line 70, in convert_book
File "calibre\ebooks\conversion\plumber.py", line 1281, in run
File "calibre_plugins.ebook_translator.convertion", line 67, in convert
File "calibre\ebooks\conversion\plugins\epub_output.py" , line 200, in convert
File "calibre\ebooks\oeb\transforms\rescale.py", line 20, in __call__
File "calibre\ebooks\oeb\transforms\rescale.py", line 43, in rescale
File "calibre\ebooks\oeb\base.py", line 1030, in data
File "calibre\ebooks\oeb\base.py", line 582, in read
FileNotFoundError: [Errno 2] No such file or directory: 'C:\\Users\\Frits\\AppData\\Local\\Temp\\calibre_6 sobh56a\\t_p8pcai_plumber\\OPS/images/cover.jpg'

Thanks for your help!

[BetterRed]

@Zetmolm - I would try giving calibre a dedicated directory for its temporary files via the CALIBRE_TEMP_DIR Environment variable.

On Windows I have it set to C:\_AppData\Calibre\Temp.

And, on Windows this 'feature' was introduced a while back, presumably because MacOS has something similar. I suspect on newish systems it's turned on by default.



Added: such features have been known to pull the rug out from under the feet of a long running application. What might make sense on a fiddle-fone OS, doesn't necessarily make sense on a desk/laptop OS.

BR

[kindlefere]

Originally Posted by Zetmolm

I got a few books translated successfully. But for several books translation ran for several hours, and then, when all units had been translated, I got a FileNotFoundError error, e.g. like the following. No translated book was created. Is there something I can do about this?

Spoiler:

....
Parsing all content...
Merging user specified metadata...
Detecting structure...
Flattening CSS and remapping font sizes...
Source base font size is 12.00000pt
Removing fake margins...
Cleaning up manifest...
Trimming unused files from manifest...
Creating EPUB Output...
translating ebook content ... (this will take a while)
Traceback (most recent call last):
File "runpy.py", line 196, in _run_module_as_main
File "runpy.py", line 86, in _run_code
File "site.py", line 83, in <module>
File "site.py", line 78, in main
File "site.py", line 50, in run_entry_point
File "calibre\utils\ipc\worker.py", line 215, in main
File "calibre\utils\ipc\worker.py", line 150, in arbitrary_n
File "calibre_plugins.ebook_translator.convertion", line 70, in convert_book
File "calibre\ebooks\conversion\plumber.py", line 1281, in run
File "calibre_plugins.ebook_translator.convertion", line 67, in convert
File "calibre\ebooks\conversion\plugins\epub_output.py" , line 200, in convert
File "calibre\ebooks\oeb\transforms\rescale.py", line 20, in __call__
File "calibre\ebooks\oeb\transforms\rescale.py", line 43, in rescale
File "calibre\ebooks\oeb\base.py", line 1030, in data
File "calibre\ebooks\oeb\base.py", line 582, in read
FileNotFoundError: [Errno 2] No such file or directory: 'C:\\Users\\Frits\\AppData\\Local\\Temp\\calibre_6 sobh56a\\t_p8pcai_plumber\\OPS/images/cover.jpg'

Thanks for your help!

If using Calibre built-in conversion feature, will you get the same error to convert to other format?

[Zetmolm]

@BetterRed, thanks for the tip. It seems however that my problem solved itself 'automagically'. I did set the CALIBRE_TEMP_DIR environment variable, but did not restart my computer so that the new setting did not take effect yet. I restarted the Translate Book function for a couple of books that had failed earlier, and almost instantly the translated versions appeared! So the temporary files were still there, and this time the plugin found them. No idea why it needs two attempts, but I'm happy that it works.

[BetterRed]

@Zetmolm - what OS are you using, Windows doesn't require a reboot after setting an EnvVar, all you have to do is restart the app that uses the EnvVar - in this case Calibre. Other OSs may require a reboot.

BR

[Zetmolm]

I'm using Windows 10 (my computer is too old to run Windows 11). I did not restart Calibre after setting the EnvVar, and the folder I assigned is still empty.

(BTW, the reason I did not restart my computer or Calibre is that a translation job is running for a huge book - 450k words, 20k units to translate. The job has been running for 24 hours now, and is not even half way yet. I expect to see the outcome when I wake up Friday morning.)