Debian Codegraph @

translations/manual/creating_plugins.pot

raw
1 # SOME DESCRIPTIVE TITLE.
2 # Copyright (C) Kovid Goyal
3 # This file is distributed under the same license as the calibre package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
5 #
6 #, fuzzy
7 msgid ""
8 msgstr ""
9 "Project-Id-Version: calibre 9.15.0\n"
10 "Report-Msgid-Bugs-To: \n"
11 "POT-Creation-Date: 2026-09-18 07:37+0530\n"
12 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
13 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
14 "Language-Team: LANGUAGE <[email protected]>\n"
15 "MIME-Version: 1.0\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
18
19 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:4
20 msgid "Writing your own plugins to extend calibre's functionality"
21 msgstr ""
22
23 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:6
24 msgid "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`."
25 msgstr ""
26
27 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:8
28 msgid "Here, we will teach you how to create your own plugins to add new features to calibre."
29 msgstr ""
30
31 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:13
32 msgid "Contents"
33 msgstr ""
34
35 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:15
36 msgid "This only applies to calibre releases >= 0.8.60"
37 msgstr ""
38
39 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:18
40 msgid "Anatomy of a calibre plugin"
41 msgstr ""
42
43 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:20
44 msgid "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."
45 msgstr ""
46
47 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:24
48 msgid "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:"
49 msgstr ""
50
51 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:32
52 msgid "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`::"
53 msgstr ""
54
55 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:38
56 msgid "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/`."
57 msgstr ""
58
59 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:42
60 msgid "You can download the Hello World plugin from :download_file:`helloworld_plugin.zip`."
61 msgstr ""
62
63 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:45
64 msgid "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, let's move on to a more complex example that actually adds a component to the user interface."
65 msgstr ""
66
67 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:50
68 msgid "A User Interface plugin"
69 msgstr ""
70
71 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:52
72 msgid "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."
73 msgstr ""
74
75 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:57
76 msgid "You can download this plugin from :download_file:`interface_demo_plugin.zip`"
77 msgstr ""
78
79 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:61
80 msgid "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``."
81 msgstr ""
82
83 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:64
84 msgid "**plugin-import-name-interface_demo.txt**"
85 msgstr ""
86
87 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:65
88 msgid "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::"
89 msgstr ""
90
91 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:71
92 msgid "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\"."
93 msgstr ""
94
95 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:76
96 msgid "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)."
97 msgstr ""
98
99 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:79
100 msgid "**__init__.py**"
101 msgstr ""
102
103 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:80
104 msgid "As before, the file that defines the plugin class"
105 msgstr ""
106
107 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:82
108 msgid "**main.py**"
109 msgstr ""
110
111 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:83
112 msgid "This file contains the actual code that does something useful"
113 msgstr ""
114
115 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:85
116 msgid "**ui.py**"
117 msgstr ""
118
119 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:86
120 msgid "This file defines the interface part of the plugin"
121 msgstr ""
122
123 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:88
124 msgid "**images/icon.png**"
125 msgstr ""
126
127 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:89
128 msgid "The icon for this plugin"
129 msgstr ""
130
131 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:91
132 msgid "**about.txt**"
133 msgstr ""
134
135 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:92
136 msgid "A text file with information about the plugin"
137 msgstr ""
138
139 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:94
140 msgid "**translations**"
141 msgstr ""
142
143 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:95
144 msgid "A folder containing .mo files with the translations of the user interface of your plugin into different languages. See below for details."
145 msgstr ""
146
147 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:99
148 msgid "Now let's look at the code."
149 msgstr ""
150
151 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:102
152 msgid "__init__.py"
153 msgstr ""
154
155 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:104
156 msgid "First, the obligatory ``__init__.py`` to define the plugin metadata:"
157 msgstr ""
158
159 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:109
160 msgid "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."
161 msgstr ""
162
163 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:114
164 msgid "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."
165 msgstr ""
166
167 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:117
168 msgid "Also there are a couple of methods for enabling user configuration of the plugin. These are discussed below."
169 msgstr ""
170
171 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:120
172 msgid "ui.py"
173 msgstr ""
174
175 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:122
176 msgid "Now let's look at ui.py which defines the actual GUI plugin. The source code is heavily commented and should be self explanatory:"
177 msgstr ""
178
179 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:128
180 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:220
181 msgid "main.py"
182 msgstr ""
183
184 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:130
185 msgid "The actual logic to implement the Interface Plugin Demo dialog."
186 msgstr ""
187
188 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:136
189 msgid "Getting resources from the plugin ZIP file"
190 msgstr ""
191
192 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:138
193 msgid "calibre's plugin loading system defines a couple of built-in functions that allow you to conveniently get files from the plugin ZIP file."
194 msgstr ""
195
196 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:140
197 msgid "**get_resources(name_or_list_of_names)**"
198 msgstr ""
199
200 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:141
201 msgid "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."
202 msgstr ""
203
204 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:150
205 msgid "**get_icons(name_or_list_of_names, plugin_name='')**"
206 msgstr ""
207
208 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:151
209 msgid "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."
210 msgstr ""
211
212 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:160
213 msgid "Enabling user configuration of your plugin"
214 msgstr ""
215
216 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:162
217 msgid "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:"
218 msgstr ""
219
220 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:173
221 msgid "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."
222 msgstr ""
223
224 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:175
225 msgid "The code to manage configuration data in the demo plugin is in config.py:"
226 msgstr ""
227
228 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:180
229 msgid "The ``prefs`` object is now available throughout the plugin code by a simple::"
230 msgstr ""
231
232 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:185
233 msgid "You can see the ``prefs`` object being used in main.py:"
234 msgstr ""
235
236 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:192
237 msgid "Edit book plugins"
238 msgstr ""
239
240 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:194
241 msgid "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`."
242 msgstr ""
243
244 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:198
245 msgid "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``."
246 msgstr ""
247
248 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:202
249 msgid "Now we create the mandatory ``__init__.py`` file that contains metadata about the plugin -- its name, author, version, etc."
250 msgstr ""
251
252 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:208
253 msgid "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."
254 msgstr ""
255
256 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:212
257 msgid "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."
258 msgstr ""
259
260 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:222
261 msgid "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."
262 msgstr ""
263
264 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:230
265 msgid "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."
266 msgstr ""
267
268 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:234
269 msgid "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."
270 msgstr ""
271
272 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:237
273 msgid "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."
274 msgstr ""
275
276 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:245
277 msgid "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."
278 msgstr ""
279
280 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:251
281 msgid "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`."
282 msgstr ""
283
284 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:259
285 msgid "Adding translations to your plugin"
286 msgstr ""
287
288 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:261
289 msgid "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."
290 msgstr ""
291
292 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:264
293 msgid "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::"
294 msgstr ""
295
296 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:269
297 msgid "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."
298 msgstr ""
299
300 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:274
301 msgid "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::"
302 msgstr ""
303
304 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:279
305 msgid "Put the .mo files into the ``translations`` folder in your plugin."
306 msgstr ""
307
308 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:281
309 msgid "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``."
310 msgstr ""
311
312 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:287
313 msgid "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::"
314 msgstr ""
315
316 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:293
317 msgid "Replace ``de`` with the language code of the language you want to test."
318 msgstr ""
319
320 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:295
321 msgid "For translations with plurals, use the ``ngettext()`` function instead of ``_()``. For example::"
322 msgstr ""
323
324 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:301
325 msgid "The plugin API"
326 msgstr ""
327
328 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:303
329 msgid "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`."
330 msgstr ""
331
332 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:306
333 msgid "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`."
334 msgstr ""
335
336 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:311
337 msgid "Debugging plugins"
338 msgstr ""
339
340 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:313
341 msgid "The first, most important step is to run calibre in debug mode. You can do this from the command line with::"
342 msgstr ""
343
344 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:317
345 msgid "Or from within calibre by right-clicking the :guilabel:`Preferences` button or using the :kbd:`Ctrl+Shift+R` keyboard shortcut."
346 msgstr ""
347
348 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:319
349 msgid "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."
350 msgstr ""
351
352 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:321
353 msgid "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."
354 msgstr ""
355
356 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:323
357 msgid "You can quickly test changes to your plugin by using the following command line::"
358 msgstr ""
359
360 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:328
361 msgid "This will shutdown a running calibre, wait for the shutdown to complete, then update your plugin in calibre and relaunch calibre."
362 msgstr ""
363
364 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:331
365 msgid "More plugin examples"
366 msgstr ""
367
368 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:333
369 msgid "You can find a list of many sophisticated calibre plugins `here <https://www.mobileread.com/forums/showthread.php?t=118764>`_."
370 msgstr ""
371
372 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:336
373 msgid "Sharing your plugins with others"
374 msgstr ""
375
376 #: ../../../home/kovid/work/calibre/manual/creating_plugins.rst:338
377 msgid "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>`_."
378 msgstr ""