calibre - en to ja translation catalogue (74 entries)

en: Writing your own plugins to extend calibre's functionality
ja: プラグインを書いて 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`.
ja: calibre の設計は非常にモジュラーです。ほとんどすべての calibre の機能がプラグインという形で提供されます。プラグインは変換、ニュースのダウンロード (ただしこれはレシピと呼ばれます)、ユーザインタフェースのさまざまな部品、いろいろなデバイスへの接続、calibre にファイルを追加する際の処理など、多岐にわたって使用されます。ビルトインのプラグインは、:guilabel:`環境設定->高度な設定->プラグイン` ですべてを確認できます。

en: Here, we will teach you how to create your own plugins to add new features to calibre.
ja: ここでは独自のプラグインを作成して calibre に新しい機能を追加する方法を説明します。

en: Contents
ja: 目次

en: This only applies to calibre releases >= 0.8.60
ja: これが適用されるのは calibre のリリース 0.8.60 以降に限られます。

en: Anatomy of a calibre plugin
ja: 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.
ja: calibre のプラグインはとてもシンプルです。Python のコードと、プラグインが必要とする画像ファイルなどのその他リソースからなる単なる ZIP ファイルにすぎません。これ以上面倒なことは避けて、基本的な例を見てみましょう。

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:
ja: EPUB および MOBI 形式のさまざまな電子ドキュメントを自己出版するために calibre をインストールしているとしましょう。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`::
ja: これでおしまいです。あとは :file:`__init__.py` を作成したフォルダで次のコードを実行するだけで、このコードを calibre にプラグインとして追加できます::

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/`.
ja: 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`.
ja: 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.
ja: calibre で本を変換するたびにプラグインの :meth:`run` メソッドが呼び出され、変換した本の発行元は "Hello World" に設定されます。これは非常に簡単なプラグインですが、ユーザインタフェースに実際にコンポーネントを追加するようなもっと複雑な例に移りましょう。

en: A User Interface plugin
ja: ユーザインタフェースプラグイン

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.
ja: このプラグインはいくつかのファイルに分散されています (コードをきれいに保つため)。ここでプラグイン ZIP ファイルからリソース (画像やデータファイル) を取得し、ユーザにプラグインの設定を許可し、calibre のユーザインタフェースに要素を作成し、calibre のデータベースにアクセスしてクエリを発行する方法を紹介します。

en: You can download this plugin from :download_file:`interface_demo_plugin.zip`
ja: このプラグインは :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``.
ja: 最初に注意すべきは、この 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::
ja: マルチファイルプラグインマジックを有効にするために使われる空のテキストファイル。このファイルは複数の .py ファイルを使うプラグインには必ず必要です。中身は空でなくてはならず、ファイル名は ``plugin-import-name-**some_name**.txt`` の形式にする必要があります。このファイルが存在すると ZIP ファイルの中にある .py ファイルからコードをインポートできるようになります。それには次のように記述します::

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".
ja: 必ずプリフィックス ``calibre_plugins`` をつける必要があります。``some_name`` は空のテキストファイルのファイル名から取得します。``some_name`` は ZIP ファイル内の :file:`some_module.py` を参照します。このインポートは Python の普通のインポートと同じくらい強力です。通常と同じように (各サボフォルダに __init__.py を定義することにより) ZIP ファイルの中に .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).
ja: ``some_name`` に使う名前はすべてのプラグインで共有するグローバルな名前空間に入るので、**可能な限り一意なものにしてください**。そしてこれは有効な Python の識別子 (英数字およびアンダースコアの使用可能) でなくてはなりません。

en: As before, the file that defines the plugin class
ja: 前述したように、プラグインクラスを定義するファイル

en: This file contains the actual code that does something useful
ja: このファイルに便利な何かを行う実際のコードが含まれます

en: This file defines the interface part of the plugin
ja: このファイルはプラグインのインタフェース部分を定義します

en: The icon for this plugin
ja: このプラグインのアイコン

en: A text file with information about the plugin
ja: このプラグインに関する情報を含むテキストファイル

en: A folder containing .mo files with the translations of the user interface of your plugin into different languages. See below for details.
ja: プラグインのユーザインタフェースを別の言語に翻訳するための .mo ファイルが入ったフォルダ

en: Now let's look at the code.
ja: ではコードを見てみましょう。

en: First, the obligatory ``__init__.py`` to define the plugin metadata:
ja: プラグインのメタデータを定義するために必須な ``__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.
ja: 注目すべき機能はフィールド :attr:`actual_plugin` だけです。calibre にはコマンドラインと GUI インタフェースが両方あるため、このような GUI プラグインは __init__.py の中で GUI ライブラリをロードすべきではありません。actual_plugin が calibre に実際のプラグインが ZIP アーカイブ内の別のファイルに見つかったことを知らせて、GUI コンテキストでのみロードされるようになります。

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.
ja: これを機能させるには、上で説明したようにプラグイン ZIP ファイルの中に plugin-import-name-some_name.txt が必要です。

en: Also there are a couple of methods for enabling user configuration of the plugin. These are discussed below.
ja: プラグインのユーザ設定を有効にする方法は、いくつか存在します。それについては下で説明します。

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:
ja: では、実際の GUI プラグインを定義している ui.py を見てみましょう。ソースコードにはコメントがちりばめられているので、読めばわかるはずです:

en: The actual logic to implement the Interface Plugin Demo dialog.
ja: Interface Plugin Demo ダイアログを実装する実際のロジック部分

en: Getting resources from the plugin ZIP file
ja: プラグイン 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.
ja: calibre のプラグイン読み込みシステムは、プラグイン ZIP ファイルからファイルを便利に取得できるようにするためのビルトイン関数をいくつか定義しています。

en: Enabling user configuration of your plugin
ja: プラグインのユーザ設定を有効にする

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:
ja: ユーザがプラグインを設定できるようにするためには、プラグインの基底クラスに 3 つのメソッド、**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.
ja: calibre には設定データを格納するのにいくつもの異なる方法があります (長い歴史の遺産です)。推奨される方法は **JSONConfig** を使用することで、これは設定情報を .json ファイルに格納します。

en: The code to manage configuration data in the demo plugin is in config.py:
ja: デモプラグインの設定データを管理するコードは config.py にあります:

en: The ``prefs`` object is now available throughout the plugin code by a simple::
ja: 次のようにするだけで ``prefs`` がプラグインコード全体から使用できりうようになります::

en: You can see the ``prefs`` object being used in main.py:
ja: ``prefs`` オブジェクトが main.py で使われているのがわかります:

en: Edit book plugins
ja: 本の編集プラグイン

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`.
ja: それでは少し趣向を変えて、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``.
ja: すべてのプラグインと同様、最初のステップは上記 :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.
ja: 次に、必須である ``__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.
ja: ひとつのエディタプラグインで複数のツールを提供できます。それぞれのツールはツールバーのひとつのボタンとエディタの :guilabel:`プラグイン` メニューのエントリに対応づけられます。ツールが複数の関連した動作を持つ場合にはサブメニューにすることも可能です。

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.
ja: ツールはすべてプラグインの中の `main.py`` に定義する必要があります。すべてのツールは :class:`calibre.gui2.tweak_book.plugin.Tool` クラスを継承するクラスです。デモプラグインの ``main.py`` を見てみましょう。ソースコードにはコメントがちりばめられているので、読めばわかるはずです。詳しくは :class:`calibre.gui2.tweak_book.plugin.Tool` クラスの API ドキュメントをお読みください。

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.
ja: ここでは、本のすべてのフォントサイズをユーザに指定された数字で掛けた大きさにするような、ひとつのツールの定義を見てみましょう。このツールは自分でプラグインを開発するときに必要となるさまざまな重要な概念を実演しているので、(コメントのちりばめられた) ソースコードをよく読んでください。

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.
ja: ``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.
ja: 最初に重要なのはツール名です。このツールのキーとして使用されるため、なるべくユニークな文字列を設定する必要があります。

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.
ja: 次に重要なエントリポイントは :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.
ja: 拡大するコードにはしっかりコメントが書き込まれていて、まあまあシンプルです。注意すべき主な点は、エディタウィンドウを ``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`.
ja: 最後に ``self.current_container`` があり、これは編集されようとしている本を :class:`calibre.ebooks.oeb.polish.container.Container` オブジェクトへの参照です。これは本をその構成要素であるHTML/CSS/画像 ファイルの集まりとして表し、役に立ついろいろなことができる便利なメソッドを備えています。プラグインコードで再利用可能なコンテナオブジェクトとさまざまな便利なユーティリティ関数については、:ref:`polish_api` に説明があります。

en: Adding translations to your plugin
ja: プラグインに翻訳を追加

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.
ja: プラグインのユーザインタフェース上のすべての文字列は翻訳して、メインの calibre ユーザインタフェースで設定された言語で表示することができます。

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::
ja: 最初のステップはプラグインのソースコードを調べ、ユーザに表示される文字列すべてを _() で囲むことにより翻訳可能としてマークすることです。

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.
ja: それから何らかのプログラムを使ってプラグインのソースコードから .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::
ja: これらの .po ファイルを翻訳者に送信しましょう。戻ってきたら .mo ファイルにコンパイルします。これにも Poedit を利用できます。または次のようにします::

en: Put the .mo files into the ``translations`` folder in your plugin.
ja: .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``.
ja: 最後のステップは、ただ単にプラグインの .pu ファイルの先頭で関数 `load_translations()` を呼び出すだけです。性能上の理由からこの関数を呼び出すのは、実際に翻訳可能な文字列が含まれている .py ファイルに限るべきです。したがって典型的なユーザインタフェースプラグインではこの関数は ``__init__.py`` ではなく ``ui.py`` の先頭で呼び出します。

en: Replace ``de`` with the language code of the language you want to test.
ja: ``de`` の部分はテスとしたい言語の言語コードに置き換えてください。

en: The plugin API
ja: プラグイン 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`.
ja: すでにお気づきかもしれませんが、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`.
ja: プラグインはほぼ確実に calibre のコードを使用します。calibre のコードベースの機能についてすみからすみまで学ぶには、calibre の:ref:`code_layout` の章をお読みください。

en: Debugging plugins
ja: デバッグプラグイン

en: The first, most important step is to run calibre in debug mode. You can do this from the command line with::
ja: 最初の、そして最も重要なステップは calibre をデバッグモードで実行することです。これはコマンドラインから次のようにして実行できます::

en: Or from within calibre by right-clicking the :guilabel:`Preferences` button or using the :kbd:`Ctrl+Shift+R` keyboard shortcut.
ja: または calibre の中で :guilabel:`環境設定` ボタンを右クリックするか、キーボードショートカットの :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.
ja: コマンドラインから実行すると、デバッグ出力はコンソール上に表示されます。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.
ja: プラグインコードのどこにでも print 文を挿入できます。これはデバッグモードで出力されます。これは Python ですから、デバッグには print 文以上のものが必要になることはありません。calibre はこのデバッグ手法だけを用いて開発されました。

en: You can quickly test changes to your plugin by using the following command line::
ja: プラグインへの変更は次のコマンドラインを使ってすぐにテストできます::

en: This will shutdown a running calibre, wait for the shutdown to complete, then update your plugin in calibre and relaunch calibre.
ja: これは calibre をシャットダウンし、シャットダウンの完了を待ち、calibre のプラグインを更新し、calibre を再起動します。

en: More plugin examples
ja: プラグインのその他の例

en: You can find a list of many sophisticated calibre plugins `here <https://www.mobileread.com/forums/showthread.php?t=118764>`_.
ja: 多くの洗練された calibre プラグインの一覧は `こちら <https://www.mobileread.com/forums/showthread.php?t=118764>`_ にあります。

en: Sharing your plugins with others
ja: プラグインの共有

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>`_.
ja: 作成したプラグインを他の calibre ユーザと共有したければ、 `calibre プラグインフォーラム <https://www.mobileread.com/forums/forumdisplay.php?f=237>`_ に新しいスレッドとして投稿してください。
