calibre - en to ru translation catalogue (78 entries)

en: Writing your own plugins to extend calibre's functionality
ru: Создание собственных плагинов для расширения функциональности calibre

en: calibre has a very modular design. Almost all functionality in calibre comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to calibre and so on. You can get a complete list of all the built-in plugins in calibre by going to :guilabel:`Preferences->Advanced->Plugins`.
ru: calibre имеет очень модульную конструкцию. Практически все функциональные возможности calibre поставляются в виде плагинов. Плагины используются для преобразования, для загрузки новостей (там они называются рецептами), для различных компонентов пользовательского интерфейса, для подключения к различным устройствам, для обработки файлов при добавлении их в calibre и так далее. Вы можете получить полный список всех встроенных плагинов в calibre, перейдя к :guilabel: `Preferences-> Advanced-> Plugins`.

en: Here, we will teach you how to create your own plugins to add new features to calibre.
ru: Здесь мы научим вас, как создавать свои собственные плагины чтобы добавить новые функции в calibre.

en: Contents
ru: Содержание

en: This only applies to calibre releases >= 0.8.60
ru: Это относится только к calibre releases >= 0.8.60

en: Anatomy of a calibre plugin
ru: Анатомия плагина calibre

en: A calibre plugin is very simple, it's just a ZIP file that contains some Python code and any other resources like image files needed by the plugin. Without further ado, let's see a basic example.
ru: Плагин calibre очень прост, это просто ZIP-файл, который содержит некоторый код Python и любые другие ресурсы, такие как файлы изображений, необходимые плагину. Без дальнейших церемоний, давайте посмотрим на основной пример.

en: Suppose you have an installation of calibre that you are using to self publish various e-documents in EPUB and MOBI formats. You would like all files generated by calibre to have their publisher set as "Hello world", here's how to do it. Create a file named :file:`__init__.py` (this is a special name and must always be used for the main file of your plugin) and enter the following Python code into it:
ru: Предположим, у вас установлена calibre, которую вы используете для самостоятельной публикации различных электронных документов в форматах EPUB и MOBI. Вы хотите, чтобы для всех файлов, сгенерированных calibre, их издатель был установлен как «Hello world», вот как это сделать. Создайте файл с именем :file:`__init__.py` (это специальное имя, которое всегда должно использоваться для основного файла вашего плагина) и введите в него следующий код Python:

en: That's all. To add this code to calibre as a plugin, simply run the following in the folder in which you created :file:`__init__.py`::
ru: Вот и всё. Чтобы добавить этот код в calibre как плагин, просто запустите в папке, в которой вы создали, следующее :file:`__init __.py`::

en: On macOS, the command line tools are inside the calibre bundle, for example, if you installed calibre in :file:`/Applications` the command line tools are in :file:`/Applications/calibre.app/Contents/MacOS/`.
ru: В macOS инструменты командной строки находятся внутри пакета calibre, например, если вы установили calibre в :file:`/Applications`, то инструменты командной строки будут в :file:`/Applications/calibre.app/Contents/MacOS/`.

en: You can download the Hello World plugin from :download_file:`helloworld_plugin.zip`.
ru: Вы можете скачать плагин Hello World из :download_file:`helloworld_plugin.zip`.

en: Every time you use calibre to convert a book, the plugin's :meth:`run` method will be called and the converted book will have its publisher set to "Hello World". This is a trivial plugin, lets move on to a more complex example that actually adds a component to the user interface.
ru: Каждый раз, когда вы используете calibre для конвертации книги, вызывается метод плагина :meth:`run`, и для конвертированной книги издателю присваивается значение "Hello World". Это тривиальный плагин, давайте перейдем к более сложному примеру, который фактически добавляет компонент в пользовательский интерфейс.

en: A User Interface plugin
ru: Плагин пользовательского интерфейса

en: This plugin will be spread over a few files (to keep the code clean). It will show you how to get resources (images or data files) from the plugin ZIP file, allow users to configure your plugin, how to create elements in the calibre user interface and how to access and query the books database in calibre.
ru: Этот плагин будет распространяться на несколько файлов (чтобы сохранить код в чистоте). Он покажет вам, как получить ресурсы (изображения или файлы данных) из ZIP-файла плагина, позволит пользователям настраивать ваш плагин, как создавать элементы в пользовательском интерфейсе calibre и как получить доступ и запросить базу данных книг в calibre.

en: You can download this plugin from :download_file:`interface_demo_plugin.zip`
ru: Вы можете скачать этот плагин из :download_file:`interface_demo_plugin.zip`

en: The first thing to note is that this ZIP file has a lot more files in it, explained below, pay particular attention to ``plugin-import-name-interface_demo.txt``.
ru: Первое, на что нужно обратить внимание, это то, что в этом ZIP-файле содержится гораздо больше файлов. Как объясняется ниже, обратите особое внимание на ``plugin-import-name-interface_demo.txt``.

en: An empty text file used to enable the multi-file plugin magic. This file must be present in all plugins that use more than one .py file. It should be empty and its filename must be of the form: ``plugin-import-name-**some_name**.txt``. The presence of this file allows you to import code from the .py files present inside the ZIP file, using a statement like::
ru: Пустой текстовый файл, используемый для включения магии многофайлового плагина. Этот файл должен присутствовать во всех плагинах, которые используют более одного файла .py. Он должен быть пустым, а его имя файла должно иметь вид: ``plugin-import-name-** some_name**.txt``. Наличие этого файла позволяет вам импортировать код из файлов .py, присутствующих в ZIP-файле, используя оператор вроде:

en: The prefix ``calibre_plugins`` must always be present. ``some_name`` comes from the filename of the empty text file. ``some_module`` refers to  :file:`some_module.py` file inside the ZIP file. Note that this importing is just as powerful as regular Python imports. You can create packages and subpackages of .py modules inside the ZIP file, just like you would normally (by defining __init__.py in each sub-folder), and everything should "just work".
ru: Всегда должен присутствовать префикс calibre_plugins. ``some_name`` происходит от имени пустого текстового файла. ``some_module`` относится к файлу :file:`some_module.py` внутри ZIP-файла. Обратите внимание, что этот импорт столь же эффективен, как и обычный импорт Python. Вы можете создавать пакеты и подпакеты модулей .py внутри ZIP-файла, как обычно (путем определения __init__.py в каждой подпапке), и все должно «просто работать».

en: The name you use for ``some_name`` enters a global namespace shared by all plugins, **so make it as unique as possible**. But remember that it must be a valid Python identifier (only alphabets, numbers and the underscore).
ru: Имя, которое вы используете для ``some_name``, входит в глобальное пространство имен, общее для всех плагинов, **поэтому сделайте его как можно более уникальным**. Но помните, что это должен быть действительный идентификатор Python (только буквы, цифры и подчеркивание).

en: As before, the file that defines the plugin class
ru: Как и прежде, файл, который определяет класс плагина

en: This file contains the actual code that does something useful
ru: Этот файл содержит реальный код, который делает что-то полезное

en: This file defines the interface part of the plugin
ru: Этот файл определяет интерфейсную часть плагина

en: The icon for this plugin
ru: Значок для этого плагина

en: A text file with information about the plugin
ru: Текстовый файл с информацией о плагине

en: A folder containing .mo files with the translations of the user interface of your plugin into different languages. See below for details.
ru: Папка, содержащая файлы .mo с переводами пользовательского интерфейса вашего плагина на разные языки. Смотрите ниже для деталей.

en: Now let's look at the code.
ru: Теперь давайте посмотрим на код.

en: First, the obligatory ``__init__.py`` to define the plugin metadata:
ru: Во-первых, обязательный ``__init__.py`` для определения метаданных плагина:

en: The only noteworthy feature is the field :attr:`actual_plugin`. Since calibre has both command line and GUI interfaces, GUI plugins like this one should not load any GUI libraries in __init__.py. The actual_plugin field does this for you, by telling calibre that the actual plugin is to be found in another file inside your ZIP archive, which will only be loaded in a GUI context.
ru: Единственная заслуживающая внимания особенность - это поле :attr:`actual_plugin`. Так как calibre имеет и командную строку, и интерфейсы GUI, плагины GUI, подобные этому, не должны загружать библиотеки GUI в __init__.py. Поле actual_plugin сделает это за вас, сообщив calibre, что фактический плагин находится в другом файле внутри вашего ZIP-архива, который будет загружен только в контексте графического интерфейса пользователя.

en: Remember that for this to work, you must have a plugin-import-name-some_name.txt file in your plugin ZIP file, as discussed above.
ru: Помните, что для этого вам понадобится файл plugin-import-name-some_name.txt в вашем ZIP-файле плагина, как обсуждалось выше.

en: Also there are a couple of methods for enabling user configuration of the plugin. These are discussed below.
ru: Также есть несколько способов включения пользовательской конфигурации плагина. Они обсуждаются ниже.

en: Now let's look at ui.py which defines the actual GUI plugin. The source code is heavily commented and should be self explanatory:
ru: Теперь давайте посмотрим на ui.py, который определяет реальный плагин GUI. Исходный код тщательно прокомментирован и должен быть понятен:

en: The actual logic to implement the Interface Plugin Demo dialog.
ru: Фактическая логика для реализации диалогового окна Interface Plugin Demo.

en: Getting resources from the plugin ZIP file
ru: Получение ресурсов из плагина ZIP-файла

en: calibre's plugin loading system defines a couple of built-in functions that allow you to conveniently get files from the plugin ZIP file.
ru: Система загрузки плагинов calibre определяет несколько встроенных функций, которые позволяют вам удобно получать файлы из ZIP-файла плагина.

en: This function should be called with a list of paths to files inside the ZIP file. For example to access the file :file:`icon.png` in the folder images in the ZIP file, you would use: ``images/icon.png``. Always use a forward slash as the path separator, even on Windows. When you pass in a single name, the function will return the raw bytes of that file or None if the name was not found in the ZIP file. If you pass in more than one name then it returns a dictionary mapping the names to bytes.  If a name is not found, it will not be present in the returned dictionary.
ru: Эта функция должна вызываться со списком путей к файлам внутри ZIP-файла. Например, чтобы получить доступ к файлу :file:`icon.png` в папке images в ZIP-файле, вы должны использовать: ``images/icon.png``. Всегда используйте косую черту в качестве разделителя пути, даже в Windows. Когда вы передаете одно имя, функция вернет необработанные байты этого файла или None, если имя не было найдено в ZIP-файле. Если вы передаете более одного имени, возвращается dict, сопоставляющий имена с байтами. Если имя не найдено, его не будет в возвращаемом dict.

en: A wrapper for get_resources() that creates QIcon objects from the raw bytes returned by get_resources. If a name is not found in the ZIP file the corresponding QIcon will be null. In order to support icon theme-ing, pass in the human friendly name of your plugin as ``plugin_name``. If the user is using an icon theme with icons for your plugin, they will be loaded preferentially.
ru: Обёртка для get_resources(), которая создает объекты QIcon из необработанных байтов, возвращенных get_resources. Если имя не найдено в ZIP-файле, соответствующий QIcon будет нулевым. Чтобы поддерживать тему значков, передайте человекопонятное имя вашего плагина как ``plugin_name``. Если пользователь использует тему значков с иконками для вашего плагина, они будут загружены в первую очередь.

en: Enabling user configuration of your plugin
ru: Включение пользовательской конфигурации вашего плагина

en: To allow users to configure your plugin, you must define three methods in your base plugin class, **is_customizable**, **config_widget** and **save_settings** as shown below:
ru: Чтобы позволить пользователям настраивать ваш плагин, вы должны определить три метода в вашем базовом классе плагинов, **is_customizable**, **config_widget** и **save_settings**, как показано ниже:

en: calibre has many different ways to store configuration data (a legacy of its long history). The recommended way is to use the **JSONConfig** class, which stores your configuration information in a .json file.
ru: calibre имеет много разных способов хранения данных конфигурации (наследие его длинной истории). Рекомендуемый способ - использовать класс **JSONConfig**, который хранит информацию о вашей конфигурации в файле .json.

en: The code to manage configuration data in the demo plugin is in config.py:
ru: Код для управления данными конфигурации в демо-плагине находится в config.py:

en: The ``prefs`` object is now available throughout the plugin code by a simple::
ru: Объект ``prefs`` теперь доступен во всем коде плагина с помощью простого::

en: You can see the ``prefs`` object being used in main.py:
ru: Вы можете увидеть объект ``prefs``, используемый в main.py:

en: Edit book plugins
ru: Редактировать книжные плагины

en: Now let's change gears for a bit and look at creating a plugin to add tools to the calibre book editor. The plugin is available here: :download_file:`editor_demo_plugin.zip`.
ru: Теперь давайте немного поменяем механизмы и посмотрим на создание плагина для добавления инструментов в редактор книг calibre. Плагин доступен здесь:download_file:`editor_demo_plugin.zip`.

en: The first step, as for all plugins is to create the import name empty txt file, as described :ref:`above <import_name_txt>`. We shall name the file ``plugin-import-name-editor_plugin_demo.txt``.
ru: Первым шагом, как и для всех плагинов, является создание пустого текстового файла с именем для импорта, как описано :ref:`above <import_name_txt>`. Мы назовем файл ``plugin-import-name-editor_plugin_demo.txt``.

en: Now we create the mandatory ``__init__.py`` file that contains metadata about the plugin -- its name, author, version, etc.
ru: Теперь мы создаем обязательный файл ``__init__.py``, который содержит метаданные о плагине -- его имя, автора, версию и т. д.

en: A single editor plugin can provide multiple tools each tool corresponds to a single button in the toolbar and entry in the :guilabel:`Plugins` menu in the editor. These can have sub-menus in case the tool has multiple related actions.
ru: Один плагин редактора может предоставлять несколько инструментов, каждый инструмент соответствует одной кнопке на панели инструментов и записи в меню :guilabel:`Plugins` в редакторе. Они могут иметь подменю, если инструмент имеет несколько связанных действий.

en: The tools must all be defined in the file ``main.py`` in your plugin. Every tool is a class that inherits from the :class:`calibre.gui2.tweak_book.plugin.Tool` class. Let's look at ``main.py`` from the demo plugin, the source code is heavily commented and should be self-explanatory. Read the API documents of the :class:`calibre.gui2.tweak_book.plugin.Tool` class for more details.
ru: Все инструменты должны быть определены в файле ``main.py`` вашего плагина. Каждый инструмент - это класс, который наследуется от класса :class:`calibre.gui2.tweak_book.plugin.Tool`. Давайте посмотрим на ``main.py`` из демо-плагина, исходный код тщательно прокомментирован и не требует пояснений. Прочитайте документы API класса :class:`calibre.gui2.tweak_book.plugin.Tool` для получения более подробной информации.

en: Here we will see the definition of a single tool that will multiply all font sizes in the book by a number provided by the user. This tool demonstrates various important concepts that you will need in developing your own plugins, so you should read the (heavily commented) source code carefully.
ru: Здесь мы увидим определение единственного инструмента, который умножит все размеры шрифта в книге на число, предоставленное пользователем. Этот инструмент демонстрирует различные важные концепции, которые вам понадобятся при разработке ваших собственных плагинов, поэтому вы должны внимательно прочитать (сильно комментированный) исходный код.

en: Let's break down ``main.py``. We see that it defines a single tool, named *Magnify fonts*. This tool will ask the user for a number and multiply all font sizes in the book by that number.
ru: Давайте разберемся с ``main.py``. Мы видим, что он определяет один инструмент с именем *Magnify fonts*. Этот инструмент запросит у пользователя число и умножит все размеры шрифтов в книге на это число.

en: The first important thing is the tool name which you must set to some relatively unique string as it will be used as the key for this tool.
ru: Первым важным моментом является имя инструмента, которое вы должны установить для некоторой относительно уникальной строки, поскольку она будет использоваться в качестве ключа для этого инструмента.

en: The next important entry point is the :meth:`calibre.gui2.tweak_book.plugin.Tool.create_action`. This method creates the QAction objects that appear in the plugins toolbar and plugin menu. It also, optionally, assigns a keyboard shortcut that the user can customize. The triggered signal from the QAction is connected to the ask_user() method that asks the user for the font size multiplier, and then runs the magnification code.
ru: Следующая важная точка входа - это :meth:`calibre.gui2.tweak_book.plugin.Tool.create_action`. Этот метод создает объекты QAction, которые появляются на панели инструментов плагинов и меню плагинов. Также, по желанию, назначается сочетание клавиш, которое пользователь может настроить. Инициированный сигнал от QAction подключается к методу ask_user(), который запрашивает у пользователя множитель размера шрифта, а затем запускает код увеличения.

en: The magnification code is well commented and fairly simple. The main things to note are that you get a reference to the editor window as ``self.gui`` and the editor *Boss* as ``self.boss``. The *Boss* is the object that controls the editor user interface. It has many useful methods, that are documented in the :class:`calibre.gui2.tweak_book.boss.Boss` class.
ru: Код увеличения хорошо прокомментирован и довольно прост. Главное, на что следует обратить внимание, это то, что вы получаете ссылку на окно редактора как ``self.gui``, а редактор *Boss* как ``self.boss``. *Boss* - это объект, который управляет пользовательским интерфейсом редактора. У него есть много полезных методов, которые описаны в классе :class:`calibre.gui2.tweak_book.boss.Boss`.

en: Finally, there is ``self.current_container`` which is a reference to the book being edited as a :class:`calibre.ebooks.oeb.polish.container.Container` object. This represents the book as a collection of its constituent HTML/CSS/image files and has convenience methods for doing many useful things. The container object and various useful utility functions that can be reused in your plugin code are documented in :ref:`polish_api`.
ru: Наконец, есть ``self.current_container``, который является ссылкой на книгу, редактируемую как объект :class:`calibre.ebooks.oeb.polish.container.Container`. Это представляет книгу как коллекцию составляющих её HTML/CSS/графических файлов и имеет удобные методы для выполнения многих полезных задач. Контейнерный объект и различные полезные служебные функции, которые можно повторно использовать в коде вашего плагина, описаны в :ref:`polish_api`.

en: Adding translations to your plugin
ru: Добавление переводов в ваш плагин

en: You can have all the user interface strings in your plugin translated and displayed in whatever language is set for the main calibre user interface.
ru: Вы можете перевести и отобразить все строки пользовательского интерфейса в вашем плагине на любом языке, установленном для основного пользовательского интерфейса.

en: The first step is to go through your plugin's source code and mark all user visible strings as translatable, by surrounding them in _(). For example::
ru: Первый шаг - просмотреть исходный код вашего плагина и пометить все видимые пользователю строки как переводимые, заключив их в _(). Например::

en: Then use some program to generate .po files from your plugin source code. There should be one .po file for every language you want to translate into. For example: de.po for German, fr.po for French and so on. You can use the `Poedit <https://poedit.net/>`_ program for this.
ru: Затем используйте какую-нибудь программу для генерации .po файлов из исходного кода вашего плагина. Для каждого языка, на который вы хотите перевести, должен быть один .po-файл. Например: de.po для немецкого, fr.po для французского и так далее. Для этого вы можете использовать программу `Poedit <https://poedit.net/>`_.

en: Send these .po files to your translators. Once you get them back, compile them into .mo files. You can again use Poedit for that, or just do::
ru: Отправьте эти .po файлы своим переводчикам. Как только вы получите их обратно, скомпилируйте их в файлы .mo. Вы можете снова использовать Poedit для этого или просто сделать::

en: Put the .mo files into the ``translations`` folder in your plugin.
ru: Поместите файлы .mo в папку ``translations`` вашего плагина.

en: The last step is to simply call the function `load_translations()` at the top of your plugin's .py files. For performance reasons you should only call this function in those .py files that actually have translatable strings. So in a typical User Interface plugin you would call it at the top of ``ui.py`` but not ``__init__.py``.
ru: Последний шаг - просто вызвать функцию `load_translations()` вверху .py файлов вашего плагина. Из соображений производительности эту функцию следует вызывать только в тех файлах .py, которые на самом деле содержат переводимые строки. Таким образом, в типичном плагине интерфейса пользователя вы бы вызвали его в верхней части ``ui.py``, но не в ``__init __.py``.

en: You can test the translations of your plugins by changing the user interface language in calibre under :guilabel:`Preferences->Interface->Look & feel` or by running calibre with the ``CALIBRE_OVERRIDE_LANG`` environment variable set. For example::
ru: Вы можете протестировать переводы ваших плагинов, изменив язык пользовательского интерфейса в calibre в разделе :guilabel:`Preferences-Interface-Look & feel` или запустив calibre с установленной переменной окружения ``CALIBRE_OVERRIDE_LANG``. Например::

en: Replace ``de`` with the language code of the language you want to test.
ru: Замените ``de`` на код языка, который вы хотите проверить.

en: For translations with plurals, use the ``ngettext()`` function instead of ``_()``. For example::
ru: Для переводов с множественным числом используйте функцию ``ngettext()`` вместо ``_()``. Например::

en: The plugin API
ru: API плагина

en: As you may have noticed above, a plugin in calibre is a class. There are different classes for the different types of plugins in calibre. Details on each class, including the base class of all plugins can be found in :ref:`plugins`.
ru: Как вы могли заметить выше, плагин calibre - это класс. Существуют разные классы для разных типов плагинов в calibre. Подробности о каждом классе, включая базовый класс всех плагинов, можно найти в :ref:`plugins`.

en: Your plugin is almost certainly going to use code from calibre. To learn how to find various bits of functionality in the calibre code base, read the section on the calibre :ref:`code_layout`.
ru: Ваш плагин почти наверняка будет использовать код из calibre. Чтобы узнать, как найти различные функциональные возможности в кодовой базе calibre, прочитайте раздел о calibre :ref:`code_layout`.

en: Debugging plugins
ru: Отладка плагинов

en: The first, most important step is to run calibre in debug mode. You can do this from the command line with::
ru: Первый, самый важный шаг - запустить calibre в режиме отладки. Вы можете сделать это из командной строки с помощью::

en: Or from within calibre by right-clicking the :guilabel:`Preferences` button or using the :kbd:`Ctrl+Shift+R` keyboard shortcut.
ru: Или изнутри calibre, щелчком правой кнопки мыши по :guilabel:`Preferences` или через сочетание клавиш :kbd:`Ctrl+Shift+R`.

en: When running from the command line, debug output will be printed to the console, when running from within calibre the output will go to a txt file.
ru: При запуске из командной строки выходные данные отладки будут выводиться на консоль, а при запуске из calibre выходные данные будут передаваться в текстовый файл.

en: You can insert print statements anywhere in your plugin code, they will be output in debug mode. Remember, this is Python, you really shouldn't need anything more than print statements to debug ;) I developed all of calibre using just this debugging technique.
ru: Вы можете вставить операторы печати в любом месте вашего кода плагина, они будут выводиться в режиме отладки. Помните, что это Python, вам действительно не нужно ничего, кроме операторов print для отладки;) Я разработал все версии calibre, используя только эту технику отладки.

en: You can quickly test changes to your plugin by using the following command line::
ru: Вы можете быстро протестировать изменения в вашем плагине, используя следующую командную строку::

en: This will shutdown a running calibre, wait for the shutdown to complete, then update your plugin in calibre and relaunch calibre.
ru: Это отключит работающий calibre, дождется завершения выключения, затем обновит ваш плагин в calibre и перезапустит calibre.

en: More plugin examples
ru: Больше примеров плагинов

en: You can find a list of many sophisticated calibre plugins `here <https://www.mobileread.com/forums/showthread.php?t=118764>`_.
ru: Вы можете найти список множества сложных плагинов calibre `здесь <https://www.mobileread.com/forums/showthread.php?t=118764>`_.

en: Sharing your plugins with others
ru: Поделиться своими плагинами с другими

en: If you would like to share the plugins you have created with other users of calibre, post your plugin in a new thread in the `calibre plugins forum <https://www.mobileread.com/forums/forumdisplay.php?f=237>`_.
ru: Если вы хотите поделиться плагинами, которые вы создали, с другими пользователями calibre, опубликуйте свой плагин в новой теме на `форуме плагинов calibre <https://www.mobileread.com/forums/forumdisplay.php?f=237. >`_.
