Skip to content

English

Jump to bottom Edit New page
书伴 edited this page May 25, 2024 · 127 revisions

English · 简体中文

Features

  • Support both "Advanced Mode" and "Batch Mode" for different usage situations.
  • Support languages supported by the selected translation engine (e.g. Google Translate supports 134 languages)
  • Support multiple translation engines, including Google Translate, ChatGPT, Gemini Pro, Claude, DeepL and so on
  • Support custom translation engine (you can configure to parse the response in JSON or XML format)
  • Support all ebook formats supported by Calibre (48 input formats, 20 output formats), as well as additional formats such as .srt and .pgn
  • Support to translate more than one ebooks (Batch Mode). The translation process of each book is carried out simultaneously without affecting one another
  • Support to review and edit translation result before outputting to ebook file (Advanced Mode)
  • Support caching translated content, with 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 https://translator.bookfere.com (you can either choose Stable Version or Rolling Version).
  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

[Advanced Mode]

  1. Choose the ebook and enter "Advanced Mode" by either:
    • clicking "Advanced Mode" from the drop-down list of the plugin icon
    • clicking the plugin icon button if "Advanced Mode" is your Preferred Mode in General Setting
  2. Select the Input Format and Target Language if needed, and click [START].
  3. [Optional] Click [Delete] button to delete the selected paragraph if you don't need to translate it.
  4. Translate the ebook by either:
    • clicking [Translate Selected] button to translate the selected paragraph
    • clicking [Translate All] button to translate the whole ebook
  5. [Optional] After translation completed, check the "Review" area at right, edit the translation result at bottom and click [SAVE] if you need to modify the text.
  6. Click [Output] button at the top right to save the ebook. The output process will be taken over by Calibre Jobs.

[ Batch Mode ]

  1. Choose the ebook(s) and enter "Batch Mode" by either:
    • clicking "Batch Mode" from the drop-down list of the plugin icon
    • clicking the plugin icon button if "Batch Mode" is your Preferred Mode in General Setting
  2. Modify the eBook title if needed for generating the output filename.
  3. Select the Target Language (and Output Format if needed).
  4. Click [TRANSLATE] button.

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.

Cache Manager

You can enter "Cache Manager" window via either ways below:

  • Click "Cache" from the drop-down list of the plugin icon
  • Follow the "Manage" link from the Cache setting of the plugin

[ Cache Path ]

  • Choose: Specify an empty folder to save all caches of the translated data. After that, not only will the old cache files (.db) be moved to the new path, but the future generated caches will also be saved here too
  • Reset: Move all cache files back to the default folder. In future, the translated data will be saved in the default folder
  • Reveal: Open the cache folder

[ Cache Data ]

  • Clear All: Delete all caches
  • Delete: Delete the selected cache file(s)

You can also delete selected cache file(s) via context menu.

Settings

You can customize the plugin through "General", "Engine" and "Content" panels.

General

[ Preferred Mode ]

  • Advanced Mode: This mode provides additional options for the translation process, allowing for more control and customization.
  • Batch Mode: This mode allows users to translate multiple ebooks at one time, streamlining the translation process and saving time.

[ 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 the specified directory

Why can't I find the translated ebooks? On Windows, there is a feature called "Storage Sense" that may cause this problem, as it automatically cleans up temporary files of long-running programs. You can try turning it off or specifying a directory to store temporary files for Calibre using its environment variable CALIBRE_TEMP_DIR.

[ Preferred Format ]

  • Input Format [default EBOOK SPECIFIC]: Set the preferred input format for ebook
  • Output Format [default EPUB]: Set the preferred output format for ebook

[ 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 1800.

[ HTTP Proxy ]

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

If your HTTP proxy requires a username or username with a password, you can append this information to the IP or domain followed by @, for example, username@127.0.0.1 or username:password@127.0.0.1 (using : to concatenate username and password).

[ Cache ]

  • Enable [default checked]: Enable to cache the translated content

Enabling the caching function can avoid re-translation of the translated content after request failure or network interruption.

To clear/delete cache or customize the cache path, you can follow the "Manage" link aside to enter "Cache Manager" window.

[ Job Log ]

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

[ Notification ]

  • Enable [default checked]: Enable showing notification once translation was completed.

[ Search Paths ]

One path per line. This plugin will search for external programs using these paths.

Engine

[ Translation Engine ]

  • Google (Free) [default]: Free translation engine
  • Google (Basic): API key required (obtain)
  • Google (Basic) ADC: Set up ADC required (instruction)
  • Google (Advanced) ADC: Set up ADC required (instruction)
  • ChatGPT (OpenAI): API key required (obtain)
  • ChatGPT (Azure): API key required (obtain)
  • Gemini Pro: API key required (obtain)
  • Claude (Anthropic): API key required (obtain)
  • DeepL: API key required (obtain)
  • DeepL (Pro): API key required (obtain)
  • DeepL (Free): Free translation engine
  • Microsoft Edge (Free): Free translation engine
  • Youdao: APP key and secret required (obtain)
  • Baidu: APP id and key required (obtain)
  • [Custom]: Customize your own translation engine

Except for Google(Free) and DeepL(Free), who does not require an API key, other built-in translation engines require you to register a corresponding account and pay to obtain an API key.

DeepL (Pro) and DeepL (Free) pertain to the DeepL API plan, distinct from the DeepL plan that includes Advanced and Ultimate options. Consequently, it is not possible to utilize them within the plugin like other CAT tools supported by DeepL.

If you intend to use the Basic or Advanced version of Google translation engine with Application Default Credentials (ADC), you have to install the Google Cloud CLI on your operating system and ensure that the gcloud command is working properly. And then Set up Application Default Credentials. For more information, please refer to the Google Cloud Translate documentation.

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 Test Translation Engine 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 as 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 JSON 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, e.g. Content-Type: application/json. 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.

[ Preferred Language ]

  • Source Language [default Auto detect]: Set the preferred source language.
  • Target Language [default UI language]: Set the preferred target language.

[ HTTP Request ]

  • Concurrency limit [default value depends on engines]: The number of concurrent requests. If set to 0, there is no limit (10 if the Calibre version is lower than 3.7).
  • Interval (seconds) [default 20 for ChatGPT, 1 for DeepL(Free), 0 for other engines]: The time interval to request translation engine
  • Attempt times [default 3]: The number of times to attempt if failed to request translation engine
  • Timeout (seconds) [default 10]: The timeout for single request to translation engine

[ Abort Translation ]

  • [default 10]: The number of consecutive errors to abort translation. After the specified number of error occurs, the translation process will stop. If set to 0, the translation process will not stop but continue until all work is completed

A single request to translation engine can last up to the specified timeout seconds. After the timeout, it will retry according to the specified attempt times, and the waiting time for each retry will be gradually increased.

We recommend increasing the 'Interval' to an appropriate value when translation interruptions occur with denial of service.

[ Tune ChatGPT ]

  • Prompt: Customize the prompt to do the translation work
  • Endpoint: The URL that provided by ChatGPT API
  • Model: Select the model from different capabilities and price points
  • Sampling: Choose to use specific temperature or top_p of OpenAI API
  • Stream: Check to enable streaming text like in ChatGPT

For more details, please refer to ChatGPT API reference and Azure OpenAI reference.

[ Tune Gemini ]

  • Prompt: Customize the prompt to do the translation work
  • temperature: Controls the randomness of the output
  • topP: The maximum cumulative probability of tokens to consider when sampling
  • topK: The maximum number of tokens to consider when sampling

For more details, please refer to Gemini Docs and Gemini API reference.

[ Tune Claude ]

  • Prompt: Customize the prompt to do the translation work
  • Endpoint: The URL that provided by Claude API
  • Model: Select the model from different capabilities and price points
  • temperature: Controls the randomness of the output
  • Sampling: Choose to use specific temperature or top_p of Claude API
  • Stream: Check to enable streaming text like in ChatGPT

For more details, please refer to __Claude API reference.

Content

[ Translation Position ]

  • Below original [default]: Add the translation text after original text
  • Above original: Add the translation text before original text
  • Right to original: Add the translation text to the right of the original text
  • Left to original: Add the translation text to the left of the original text
  • With no original: Add the translation text and delete original text

When you choose the right or left position, you can customize the column gap method:

  • Percentage [default 10]: Set the column gap width as a percentage of the horizontal page width.
  • Space count [default 8]: Use the specified number of non-breaking spaces as the column gap.

[ Original Text Color ]

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

[ Translation Text 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.

[ 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

[ Priority Element ]

CSS selectors for priority elements. One rule per line. e.g. section, #content, div.portion. Namely, stop futher extraction once elements match these rules.

[ Ignore Element ]

CSS selectors for ignoring elements. One rule per line. e.g. table, table#report, table.list. Namely, Do not translate elements that match these rules.

[ Ignore Paragraph ]

Do not translate extracted elements that match these rules.

  • Scope
    • Text only [default]: Matches only the text
    • HTML element: Matches the entire HTML element
  • Mode
    • 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.

[ Reserve Element ]

CSS selectors for keeping elements. One rule per line. e.g. table, table#report, table.list. Namely, keep elements that match these rules for extraction.

[ Ebook Metadata ]

  • Metadata translation [default unchecked]: Translate all of the metadata information.
  • Language Mark [default unchecked]: Append the target language to the metadata title.
  • Language Code [default unchecked]: Replace the language in metadata with "Target Language".
  • Append Subjects: Add the specified subjects to metadata (one subject per line).

♥ by bookfere.com

English

简体中文

Clone this wiki locally