calibre - en to fi translation catalogue (64 entries)

en: Writing your own plugins to extend calibre's functionality
fi: Omien lisäosien luominen calibren ominaisuuksia laajentamaan

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`.
fi: Calibren rakenne on hyvin modulaarinen. Lähes kaikki toiminnot on toteutettu lisäosien kautta. Lisäosia käytetään muuntamiseen, uutisten lataamiseen (vaikka niitä silloin kutsutaan resepteiksi), käyttöliittymän eri osiin, eri laitteisiin yhdistämiseen, tiedostojen muokkaamiseen kun niitä lisätään calibreen jne. Löydät täydellisen listan kaikista sisäänrakennetuista lisäosista avaamalla :guilabel:'Asetukset -> Edistyneet asetukset -> Lisäosat'.

en: Here, we will teach you how to create your own plugins to add new features to calibre.
fi: Tässä opastamme sinua omien lisäosien tekemisessä uusien toimintojen lisäämiseksi calibreen

en: Contents
fi: Sisältö

en: This only applies to calibre releases >= 0.8.60
fi: Koskee vain calibre versioita <=0.8.60

en: Anatomy of a calibre plugin
fi: calibre-lisäosan rakenne

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.
fi: calibre-lisäosa on hyvi yksinkertainen, ZIP-tiedostossa hiukan Python-koodia ja mahdolliset lisäosan tarvitsemat lisäresurssit, kuten kuvia. Katsotaanpa sitten yksinkertaista esimerkkiä.

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:
fi: Jos vaikkapa käytät calibrea omien e-dokumenttiesi julkaisuun EPUB. tai MOBI-formaatissa, ja haluat asettaa kaikkiin calibren tuottamiin tiedostoihin julkaisijaksi "Hello world", tee näin. Luo tiedosto nimellä :file:'__init__.py' (lisäosan päätiedosto on aina tämän niminen) ja kirjoita siihen tämä Python-koodi:

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.
fi: Aina muuntaessa kirjan calibrella, lisäosan :meth:'run'-metodia kutsutaan ja muunnetun kirjan julkaisijaksi asetetaan "Hello World". Tämän yksinkertaisen lisäosan myötä voimme siirtyä mutkikkaampaan lisäosaan, joka tuo uuden komponentin käyttöliittymään.

en: A User Interface plugin
fi: Käyttäjäliittymä liitännäinen

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.
fi: Lisäosa muodostuu muutamasta tiedostosta (jotta koodi säilyy selkeänä). Se esittelee sinulle tavat hakea resursseja (kuvia tai tietoja) lisäosan ZIP-tiedostosta, sallia käyttäjien muokata lisäosan asetuksia, kuinka lisätä käyttöliittymään elementtejä sekä miten calibre-tietokantaan tehdään kyselyjä.

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``.
fi: Ensimmäisenä huomaat että ZIPissä on paljon enemmän tiedostoja - nämä kuvataan alla, mutta kiinnitä huomiota erityisesti tiedostoon ``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::
fi: Tyhjä tekstitiedosto, joka mahdollistaa usean tiedoston lisäosatoiminnan. Tämän tiedoston on oltava kaikissa enempää kuin yhtä .py-tiedostoa käyttävissä lisäosissa. Se pidetään tyhjänä ja nimen on oltava muotoa: ``plugin-import-name-**jokin_nimi**.txt``. Tiedoston läsnäolo mahdollistaa koodin tuomisen ZIPin .py-tiedostoista, käyttämällä komentoja kuten::

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).
fi: Nimi jonka annat "jokin_nimi"-kohtaan tulee lisäosien jaettuun nimiavaruuteen, **joten tee siitä mahdollisimman yksilöllinen**. Muista kuitenkin noudattaa luvallisia Python-tunnistemuotoa (vain aakkosia, numeroita ja alaviiva).

en: As before, the file that defines the plugin class
fi: Kuten edellä, lisäosan luokan määrittävä tiedosto

en: This file contains the actual code that does something useful
fi: Tämä tiedosto sisältää varsinaisen toiminnallisen koodin

en: This file defines the interface part of the plugin
fi: Tämä tiedosto määritää lisäosan käyttöliittymän

en: The icon for this plugin
fi: Lisäosan kuvake

en: A text file with information about the plugin
fi: Tekstitiedosto jossa on tietoa lisäosasta

en: A folder containing .mo files with the translations of the user interface of your plugin into different languages. See below for details.
fi: Kansio .mo-tiedostoja joissa on lisäosasi käyttöliittymän käännökset eri kielille. Katso lisätietoja alta.

en: Now let's look at the code.
fi: Katsotaan nyt koodia.

en: First, the obligatory ``__init__.py`` to define the plugin metadata:
fi: Ensin, pakollinen "__init__.py" joka määrittää lisäosan metatiedot:

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.
fi: - Ainoa huomionarvoinen ominaisuus on kenttä :attr:`actual_plugin`. Koska calibressa on sekä komentorivi- että GUI-käyttöliittymät, tällaisten lisäosien ei pitäisi ladata käyttöliittymäkirjastoja __init__.py:ssä. Sen sijaan kenttä actual_plugin vastaa tästä, kertomalla calibrelle, että varsinainen lisäosa löytyy toisesta tiedostosta ZIPissä, ja se ladataan vain GUI-kontekstissa.

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.
fi: Muista että toiminnan ehtona lisäosan ZIPissä on oltava tiedosto plugin-import-name-jokin_nimi.txt, kuten yllä mainittiin.

en: Also there are a couple of methods for enabling user configuration of the plugin. These are discussed below.
fi: Pari metodia mahdollistaa käyttäjäasetusten tekemisen. Niistä lisää alla.

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:
fi: Seuraavaksi ui.py:stä, joka määrittää GUI-lisäosan. Tämä lähdekoodi on perusteellisesti kommentoitu ja sen pitäisi olla aika selkeä:

en: The actual logic to implement the Interface Plugin Demo dialog.
fi: Varsinainen logiikka, jolla Interface Plugin Demo -ikkuna suoritetaan.

en: Getting resources from the plugin ZIP file
fi: Resurssien hakeminen lisäosan ZIP-tiedostosta

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.
fi: calibren lisäosien lataustoiminto tarjoaa pari sisäänrakennettua funktiota joilla voit sujuvasti hakea tiedostoja lisäosa-ZIPistä.

en: Enabling user configuration of your plugin
fi: Käyttäjäasetusten salliminen lisäosassa

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:
fi: Jotta lisäosan asetukset ovat käyttäjien muokattavissa, vaaditaan kolmen metodin määrittäminen lisäosan base-luokassa, **is_customizable**, **config_widget** ja **save_settings** alla olevan esimerkin mukaisesti:

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.
fi: calibrella on useita keinoja tallentaa asetustietoja (kiitos pitkän historiansa). Suositeltu tapa on **JSONConfig**-luokan käyttäminen, jolloin asetustiedot tallentuvat .json-tiedostoon.

en: The code to manage configuration data in the demo plugin is in config.py:
fi: Asetustietojen hallintakoodi on demo-lisäosan config.py:ssä:

en: The ``prefs`` object is now available throughout the plugin code by a simple::
fi: "prefs"-objekti on nyt käytettävissä lisäosakoodista käyttäen yksinkertaista::

en: You can see the ``prefs`` object being used in main.py:
fi: "prefs"-objektin käytöstä näet esimerkin main.py:ssä:

en: Edit book plugins
fi: Muokkaa kirja-liitännäisiä

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``.
fi: Ensimmäinen askel, kuten kaikille lisäosille, on luoda tuontinimen tyhjä txt-tiedosto, kuten kerrottu :ref:'yllä <import_name_txt>'. Nimetään tämä ``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.
fi: Sitten luodaan pakollinen "__init__.py"-tiedosto jossa on lisäosan metatiedot - sen nimi, tekijä, versio jne.

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.
fi: Yksittäinen muokkauslisäosa voi tarjota useampia työkaluja joista kukin vastaa yhtä työkalurivin painiketta ja riviä muokkaimen :guilabel:'Lisäosat'-valikossa. Myös alivalikoita voi asettaa jos työkalulla on rinnakkaisia toimintoja.

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.
fi: Kaikki työkalut määritellään lisäosasi "main.py":ssä. Kukin työkalu on luokka, joka perii :class:`calibre.gui2.tweak_book.plugin.Tool` luokan. Käydään läpi demo-lisäosan "main.py", jonka koodi on perusteellisesti kuvattu ja helposti ymmärrettävä. Lue API-dokumentaatio class:`calibre.gui2.tweak_book.plugin.Tool` -luokalle saadaksesi tarkempia tietoja.

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.
fi: Tämä määrittely on yksittäinen työkalu, joka monistaa kaikki tekstikoot kirjassa käyttäjän asettamalla kertoimella. Työkalu demonstroi useita tärkeitä konsepteja joita tarvitset omien lisäosiesi luomisessa, joten perehty lähdekoodin kuvauksiin huolellisesti.

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.
fi: Käydään läpi "main.py". Se määrittää yhden työkalun, nimeltä "Magnify fonts". Työkalu kysyy käyttäjältä lukua ja kertoo sillä kaikki kirjan tekstikoot.

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.
fi: Ensimmäinen huomattava asia on, että työkalun nimen tulee olla suhteellisen uniikki lauseke, sillä se toimii työkalun tunnuksena.

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.
fi: Toiseksi, tärkein lähtöpiste on :meth:`calibre.gui2.tweak_book.plugin.Tool.create_action`. Tämä metodi luo QAction-objektit jotka näkyvät lisäosatyökalurivillä ja lisäosavalikossa. Sen avulla voi myös asettaa näppäinoikotien jonka käyttäjä voi mukauttaa. QActionin kutsuma signaali liittyy ask_user() metodiin joka pyytää käyttäjältä tekstikoon kerrointa, ja suorittaa sitten skaalauskoodin.

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.
fi: Skaalauskoodi on kuvattu perusteellisesti ja aika yksinkertainen. Huomaa erityisesti viittaaminen muokkainikkunaan "self.gui":na ja muokkain *Boss*iin "self.boss":na. *Boss* on objekti joka ohjaa muokkaimen käyttöliittymää. Sillä on paljon hyödyllisiä metodeja, jotka on kuvattu :class:`calibre.gui2.tweak_book.boss.Boss` luokassa.

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`.
fi: Lopuksi, "self.current_container" joka viittaa muokattavaan kirjaan :class:`calibre.ebooks.oeb.polish.container.Container`-objektina. Sen kautta kirja näkyy kokoelmana HTML/CSS/kuvatiedostojaan, ja sisältää metodeja moniin hyödyllisiin toimintoihin. container-objekti ja käytännöllisiä aputoimintoja joita voit käyttää lisäosakoodissasi on dokumentoitu :ref:`polish_api`:ssa.

en: Adding translations to your plugin
fi: Lisätään käännös liitännäiseen

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.
fi: Kaikki käyttöliittymätekstit voidaan kääntää ja esittää millä tahansa kielellä jota calibren käyttöliittymä on asetettu käyttämään.

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::
fi: Käy ensin läpi lisäosan koodi ja merkitse kaikki teksti käännettäviksi ympäröimällä ne _():lla. Esimerkiksi::

en: Put the .mo files into the ``translations`` folder in your plugin.
fi: Laita .mo-tiedostot lisäosasi "translations"-kansioon.

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``.
fi: Viimeinen vaihe on kutsua funktiota `load_translations()` lisäosasi .py-tiedostojen alussa. Suorituskykysyistä tee kutsu vain niissä .py-tiedostoissa joissa on käännettävää tekstiä. Eli tavallisesti kutsuisit käännöstä "ui.py":ssä, mutta et "__init__.py":ssä.

en: Replace ``de`` with the language code of the language you want to test.
fi: Korvaa "de" haluamasi kielen kielikoodilla.

en: The plugin API
fi: Liitännäinen 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`.
fi: Kuten ehkä huomasit, lisäosa on calibressa luokka. Erityyppisille lisöosille on calibressa eri luokat. Lisätietoja luokista löytyy kohdasta :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`.
fi: Lisäosasi käyttää melko varmasti calibren koodia. Oppiaksesi calibren koodikannan toiminnoista, lue calibren :ref:`code_layout`.

en: Debugging plugins
fi: Lisäosien virheenetsintä

en: The first, most important step is to run calibre in debug mode. You can do this from the command line with::
fi: Ensinnäkin, käynnistä calibre virheenetsintätilassa. Se onnistuu komentoriviltä kutsulla::

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.
fi: Komentoriviltä käynnistettynä virheenetsintäraportti tulostuu komentorivi-ikkunaan, calibren sisällä käynnistettynä raportointi tulee txt-tiedostoon.

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.
fi: Voit asettaa lisäosaasi mihin tahansa print-lausekkeen, jolloin ne tallentuvat virheenetsintätilassa. Muista, tämä on Python, printin pitäisi riittää virheenetsintään ;) Olen rakentanut koko calibren pelkästään sen avulla.

en: You can quickly test changes to your plugin by using the following command line::
fi: Lisäosan muutoksia voi nopeasti testata komentoriviltä näin::

en: This will shutdown a running calibre, wait for the shutdown to complete, then update your plugin in calibre and relaunch calibre.
fi: calibre sammutetaan, sammumisen jälkeen lisäosa päivitetään ja calibre käynnistyy uudestaan.

en: More plugin examples
fi: Lisää esimerkkejä liitännäisistä

en: Sharing your plugins with others
fi: Jaa liitännäinen

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>`_.
fi: Jos haluat jakaa lisäosasi muille käyttäjille, lataa lisäosasi uuteen ketjuun `calibre plugins forumilla <https://www.mobileread.com/forums/forumdisplay.php?f=237>`_.
