addons21.txt

/////
++++++++++++++++++++++++++++++
<%def name="title()">
Writing Anki 2.1.x Add-ons
</%def>

<h1>Writing Anki 2.1.x Add-ons</h1>
++++++++++++++++++++++++++++++
/////

_ Anki 2.1.x アドオンの作成 _

/////
= Other Versions =
/////

= 他のバージョン =

/////
This document covers add-on writing for the (not yet released) Anki 2.1.x. For
instructions on writing add-ons for Anki 2.0.x, please see
https://apps.ankiweb.net/docs/addons.html
/////

この文書では、まだリリースしていませんが Anki 2.1.x 用のアドオンの作成について扱います。Anki 2.0.x 用については https://apps.ankiweb.net/docs/addons.html をご覧ください。

/////
= Translations =
/////

= 他の言語 =

/////
 * 日本語: http://rs.luminousspice.com/ankiaddons21/
 * по-русски: http://finpapa.ucoz.ru/ankitest-addons.html#addons21
/////

 * 英語 (原文): https://apps.ankiweb.net/docs/addons21.html
 * ロシア語: http://finpapa.ucoz.ru/ankitest-addons.html#addons21

/////
= Overview =
/////

= 概要 =

/////
Anki is written in a user-friendly language called Python. If you're not
familiar with Python, please read the http://docs.python.org/tutorial/[Python
tutorial] before proceeding with the rest of this document.
/////

Anki は、ユーザーフレンドリーなプログラミング言語 Python で作成しています。
Python についてあまり詳しくない方は、この文書の先を読む前に
http://docs.python.org/tutorial/[Python tutorial] をお読みください。
(訳注: https://docs.python.org/ja/3/tutorial/[Python チュートリアル
日本語版])

/////
Because Python is a dynamic language, add-ons are extremely powerful in Anki -
not only can they extend the program, but they can also modify arbitrary
aspects of it, such as altering the way scheduling works, modifying the UI,
and so on.
/////

Python は動的言語なため、Anki ではアドオンが極めて強力に機能します。アドオンは Anki の処理
を拡張するだけでなく、Anki の任意の側面に変更を加えることができます。例えば、スケジュール
設定の処理を変更したり、ユーザーインターフェイスを修正したりすることができます。

/////
No special development environment is required to develop add-ons. All you
need is a text editor. If you're on Windows or a Mac, please use the packaged
version of Anki that's provided on the website, as there are no instructions
available for building it from scratch on those platforms.
/////

プラグインの開発には、特別な開発環境は必要ありません。テキストエディタがあれば十分です。
Windows や Mac をお使いの方は、このサイトで提供しているパッケージ版の Anki をお使いください。これらの
プラットフォーム上でゼロから Anki を構築するための説明が入手できないためです。

/////
While you can write plugins in a simple text editor like notepad, you may want
to look into an editor that can provide syntax highlighting (colouring of the
code) to make things easier.
/////

メモ帳のような単純なテキストエディタでプラグインを作成できますが、シンタックスハイライト
機能 (コードの色分け) を持ったエディタを探してみると、作業がより簡単になります。

/////
Anki is comprised of two parts: 
/////

Anki を構成する2つの要素

/////
'anki' contains all the "backend" code - opening collections, fetching and
answering cards, and so on. It is used by Anki's GUI, and can also be included
in command line programs to access Anki decks without the GUI.
/////

'anki' には、「背後」で動作する全てのコードが含まれています。コレクションを開いたり、
カードを取得し、回答する処理などです。これは、Anki の GUI が使用していますが、GUI を使わず
に Anki 単語帳にアクセスするコマンドラインプログラムに含めることもできます。

/////
'aqt' contains the UI part of Anki. Anki's UI is built upon PyQt, Python
bindings for the cross-platform GUI toolkit Qt. PyQt follows Qt's API very
closely, so the documentation can be very useful when you want to know how to
use a particular GUI component.
/////

'aqt' には、Anki のユーザーインターフェイスの部分が含まれています。Anki のユーザー
インターフェイスは、PyQt 上に構築されています。PyQt とは、クロスプラットフォーム GUI
ツールキット Qt に対する Python バインディングです。PyQt は、Qt の API に密接に動作
します。Qt documentation は、特定の GUI
コンポーネントの使い方を調べたい時に、非常に役立ちます。

/////
Anki 2.1.x uses http://doc.qt.io/qt-5/index.html[Qt 5.9]
/////

Anki 2.1.x は http://doc.qt.io/qt-5/index.html[Qt 5.9] を使用しています。

/////
When Anki starts up, it checks for modules in the add-ons folder, and runs
each one it finds. When add-ons are run, they typically modify existing code
or add new menu items to provide a new feature.
/////

Anki が起動すると、アドオンフォルダ内のモジュールを確認し、見つけたモジュールを一つづつ実行します。アドオンを実行すると、通常は既存のコードを変更したり、新しい機能を呼び出すメニュー項目を新たに追加します。

/////
= Add-on folders =
/////

= アドオンフォルダ =

/////
You can access the top level add-ons folder by going to the Tools>Add-ons menu
item in the main Anki window. Click on the View Files button, and a folder
will pop up. If you had no add-ons installed, the top level add-ons folder
will be shown. If you had an add-on selected, the add-on's module folder will
be shown, and you will need to go up one level.
/////

Anki のメインウィンドウのメニューから Tools>Add-ons と選ぶと、アドオンフォルダの最上位階層にアクセスできます。View Files ボタンを押すとフォルダがポップアップします。アドオンをまだ何もインストールしていない場合は、最上位のアドオンフォルダが開きます。アドオンを選択している場合は、アドオンのモジュールフォルダが開きます。これは最上位階層の一つ下の階層になります。

/////
The add-ons folder is named "addons21", corresponding to Anki 2.1. If you have
an "addons" folder, it is because you have previously used Anki 2.0.x.
/////

アドオンフォルダの名前は、"addons21"　です。Anki 2.1 に対応しています。"addons" があるのは、以前 Anki 2.0.x を使っていたためです。

/////
Each add-on uses one folder inside the add-on folder. Anki looks for a
file called `__init__.py` file inside the folder, eg:
/////

それぞれのアドオンは、アドオンフォルダの中の一つのフォルダを使います。Anki はそのフォルダの中にあるファイル `__init__.py` を探します。

  addons21/my_addon/__init__.py

/////
If `__init__.py` does not exist, Anki will ignore the folder.
/////

もし `__init__.py` がなければ、Anki はそのフォルダを無視します。

/////
When choosing a folder name, it is recommended to stick to a-z and 0-9
characters to avoid problems with Python's module system.
/////

フォルダ名を決めるときには、a-z と 0-9 の範囲の文字から選ぶことおすすめします。これによって、Python モジュールシステムによる問題を避けることができます。

/////
While you can use whatever folder name you wish for folders you create
yourself, when you download an add-on from AnkiWeb, Anki will use the item's
ID as the folder name, such as:
/////

自分でフォルダを作るときはどんな名前でも使えますが、AnkiWeb からアドオンをダウンロードするときは、Anki はそのアドオンの ID をフォルダ名に使います。例えば次の通りです。

 addons21/48927303923/__init__.py

/////
Anki will also place a meta.json file in the folder, which keeps track of the
original add-on name, when it was downloaded, and whether it's enabled or not.
/////

Anki はさらにフォルダに meta.json ファイルを保存して、ダウンロードした時の元のアドオン名と、アドオンの利用許可を追跡ます。

/////
You should not store user data in the add-on folder, as it's
<<configuration,deleted when the user upgrades an add-on>>.
/////

ユーザーデータをアドオンフォルダに保存できません。<<configuration,そのようなデータは、ユーザーがアドオンをアップグレードすると、削除される>>からです。

/////
= A Simple Add-On =
/////

= 簡単なアドオンの一例 =

/////
Add the following to `my_first_addon/__init__.py` in your add-ons folder:
/////

次に示す `my_first_addon/__init__.py` を、自分のアドオンフォルダに追加してみてください:

/////
-----
# import the main window object (mw) from aqt
from aqt import mw
# import the "show info" tool from utils.py
from aqt.utils import showInfo
# import all of the Qt GUI library
from aqt.qt import *

# We're going to add a menu item below. First we want to create a function to
# be called when the menu item is activated.

def testFunction():
    # get the number of cards in the current collection, which is stored in
    # the main window
    cardCount = mw.col.cardCount()
    # show a message box
    showInfo("Card count: %d" % cardCount)

# create a new menu item, "test"
action = QAction("test", mw)
# set it to call testFunction when it's clicked
action.triggered.connect(testFunction)
# and add it to the tools menu
mw.form.menuTools.addAction(action)
-----
/////

-----
# aqt からメインウィンドウオブジェクト (mw) を読み込みます
from aqt import mw
# utils.py から "show info" ツールを読み込みます
from aqt.utils import showInfo
# Qt GUI ライブラリの全てを読み込みます
from aqt.qt import *

# 次のようなメニュー項目を追加してみましょう。まず最初にメニュー項目が利用可能になったら
# 呼び出す関数を作成します。

def testFunction():
    # 現在使用中のコレクションの中のカードの枚数を取得します
    # このコレクションはメインウィンドウの中に保存しています
    cardCount = mw.col.cardCount()
    # メッセージボックスを表示します
    showInfo("Card count: %d" % cardCount)

# 新しいメニュー項目 "test" を作成します。
action = QAction("test", mw)
# この項目をクリックしたら testFunction を呼び出すように設定します。
action.triggered.connect(testFunction)
# そして、この設定をツールメニューに反映します。
mw.form.menuTools.addAction(action)
-----

/////
Restart Anki, and you should find a 'test' item in the tools menu. Running it
will display a dialog with the card count.
/////

Anki を再起動すると、ツールメニューの中に 'test' 項目が追加されていることに気づくでしょう。
この項目を選択して実行するとカード枚数を表示するダイアログが現れます。

/////
If you make a mistake when entering in the plugin, Anki will show an error
message on startup indicating where the problem is.
/////

プラグインの入力中に間違いがあった場合には、Anki は起動時にエラーメッセージを表示して
どこに問題があるか指摘します。

/////
= The Collection =
/////

= コレクション =

/////
All operations on a collection file are accessed via mw.col. Some basic
examples of what you can do follow. Please note that you should put these in
testFunction() as above. You can't run them directly in an add-on, as add-ons
are initialized during Anki startup, before any collection or profile has been
loaded.
/////

コレクションファイル上の全ての操作は、mw.col を通じてアクセスします。基本的な例で
何ができるがご紹介します。注意してほしいのは、上の例のように testFunction() の中で行ってください。
アドオンの中で直接実行することはできません。それは、Anki を起動中にアドオンが初期化し、その後にコレクションやプロファイルを
読み込むからです。

/////
*Get a due card:*
/////

*復習時期のカードの取得:*

/////
-----
card = mw.col.sched.getCard()
if not card:
    # current deck is finished
-----
/////

-----
card = mw.col.sched.getCard()
if not card:
    # 現在の単語帳は復習済み
-----

/////
*Answer the card:*
/////

*カードを解答する:*

-----
mw.col.sched.answerCard(card, ease)
-----

/////
*Edit a note (append " new" to the end of each field):*
/////

*ノートを編集する (各フィールドの最後に " new" を追加):*

-----
note = card.note()
for (name, value) in note.items():
    note[name] = value + " new"
note.flush()
-----

/////
*Get card IDs for notes with tag x:*
/////

*ノートにタグ x を持つカードの ID を取得する:*


-----
ids = mw.col.findCards("tag:x")
-----

/////
*Get question and answer for each of those ids:*
/////

*指定したカード ID から質問と解答を取得する:*


-----
for id in ids:
    card = mw.col.getCard(id)    
    question = card.q()
    answer = card.a()
-----

/////
*Reset the scheduler after any DB changes. Note that we call reset() on the
main window, since the GUI has to be updated as well:*
/////

*データベースの変更後にスケジュールをリセットする。GUI も更新しなければならないので、
メインウィンドウ上で reset() を呼び出すことに注意してください:*

-----
mw.reset()
-----

/////
*Import a text file into the collection*
/////

*テキストファイルをコレクションに読み込む*

/////
-----
from anki.importing import TextImporter
file = u"/path/to/text.txt"
# select deck
did = mw.col.decks.id("ImportDeck")
mw.col.decks.select(did)
# set note type for deck
m = mw.col.models.byName("Basic")
deck = mw.col.decks.get(did)
deck['mid'] = m['id']
mw.col.decks.save(deck)
# import into the collection
ti = TextImporter(mw.col, file)
ti.initMapping()
ti.run()
-----
/////

-----
from anki.importing import TextImporter
file = u"/path/to/text.txt"
# 単語帳を選択
did = mw.col.decks.id("ImportDeck")
mw.col.decks.select(did)
# 単語帳にノートタイプを設定
m = mw.col.models.byName("Basic")
deck = mw.col.decks.get(did)
deck['mid'] = m['id']
mw.col.decks.save(deck)
# コレクションに読み込む
ti = TextImporter(mw.col, file)
ti.initMapping()
ti.run()
-----

/////
Almost every GUI operation has an associated function in anki, so any of
the operations that Anki makes available can also be called in an add-on.
/////

ほとんど全ての GUI 処理は 'anki' 内に関連する関数を持っています。このため、Anki が利用
できるどんな処理でも、アドオンの中で同様に呼び出すことができます。

/////
If you want to access the collection outside of the GUI, you can do so with
the following code:
/////

GUI の外側のコレクションにアクセスする場合は、次のようなコードを使います:

-----
from anki import Collection
col = Collection("/path/to/collection.anki2")
-----

/////
If you make any modifications to the collection outside of Anki,
you must make sure to call col.close() when you're done,
or those changes will be lost.
/////

Anki の外部のコレクションに何らかの修正を加えたときは、修正が済んだら col.close() を必ず呼び出さなければなりません。
これを怠ると修正点は失われます。

/////
= The Database =
/////

= データベース =

/////
When you need to perform operations that are not already supported by anki,
you can access the database directly. Anki collections are stored in SQLite
files. Please see the http://www.sqlite.org/lang.html[SQLite documentation]
for more information.
/////

'anki' がサポートしていない処理を実行する必要がある場合は、データベースに直接アクセスする
ことができます。Anki コレクションは、SQLite ファイル内に保存されています。詳しい情報は、
http://www.sqlite.org/lang.html[SQLite documentation]をご覧ください。

/////
Anki's DB object supports the following functions:
/////

Anki のデータベースオブジェクトは次のような関数をサポートしています:

/////
*execute() allows you to perform an insert or update operation. Use named
arguments with ?. eg:*
/////

*execute() は、挿入と更新処理を実行します。指定した引数は ? を一緒に使います。例えば:*

-----
mw.col.db.execute("update cards set ivl = ? where id = ?", newIvl, cardId)
-----

/////
*executemany() allows you to perform bulk update or insert operations. For
large updates, this is much faster than calling execute() for each data point.
eg:*
/////

*executemany() は、更新と挿入を一括処理します。大規模な更新にはこの関数の方が、
execute() で個別にデータを処理するよりも非常に高速に処理します。例えば:*

-----
data = [[newIvl1, cardId1], [newIvl2, cardId2]]
mw.col.db.executemany(same_sql_as_above, data)
-----

/////
*scalar() returns a single item:*
/////

*scalar() は、単一の項目を返します:*

-----
showInfo("card count: %d" % mw.col.db.scalar("select count() from cards"))
-----

/////
*list() returns a list of the first column in each row, eg [1, 2, 3]:*
/////

*list() は、各行の最初の列をリストで返します。次のコードの戻り値は [1, 2, 3]です:*

-----
ids = mw.col.db.list("select id from cards limit 3")
-----

/////
*all() returns a list of rows, where each row is a list:*
/////

*all() は、各行がリストの場合、行のリストを返します:*

-----
ids_and_ivl = mw.col.db.all("select id, ivl from cards")
-----

/////
*execute() can also be used to iterate over a result set without building an
intermediate list. eg:*
/////

*execute() は、中間リストを作らずに結果の集合への処理を繰り返すのに使えます。例:*

-----
for id, ivl in mw.col.db.execute("select id, ivl from cards limit 3"):
    showInfo("card id %d has ivl %d" % (id, ivl))
-----

/////
Add-ons should never modify the schema of existing tables, as that may
break future versions of Anki.
/////

アドオンは、既存のテーブルのスキーマを決して変更してはいけません。そうすると将来のバージョンの Anki を破壊するかもしれないからです。

/////
If you need to store addon-specific data, consider using Anki's
<<configuration>> support.
/////

アドオン独自のデータが必要な場合は、Anki の <<configuration, 設定>> サポートの使用を考慮してください。

/////
If you need the data to sync across devices, small options can be stored
within mw.col.conf. Please don't store large amounts of data there, as
it's sent on every sync.
/////

デバイス間でデータを同期する必要する場合は、小さな設定項目を mw.col.conf に保存できます。そこに大量なデータは保存しないでください。同期のたびに送ることになるからです。

/////
= Hooks =
/////

= フック =

/////
Hooks have been added to a few parts of the code to make writing add-ons
easier. There are two types: 'hooks' take some arguments and return no value,
and 'filters' take a value and return it (perhaps modified).
/////

フックをコードのわずかな箇所に追加して、アドオンの作成がもっと簡単になるようにしました。
フックは 2 種類あります。'hooks' は引数を取り、戻り値はありませんが、'filters' 引数を取り、
(おそらく何らかの修正を加えて) 値を返します。

/////
A simple example of the former is in the leech handling. When the scheduler
(anki/sched.py) discovers a leech, it calls:
/////

'hook' の簡単な例は、無駄なカード (leech) の処理の中に見つかります。スケジューラー
(anki/sched.py) が、無駄なカードを見つけると、'hook' を呼び出します。

-----
runHook("leech", card)
-----

/////
If you wished to perform a special operation when a leech was discovered, such
as moving the card to a "Difficult" deck, you could do it with the following
code:
/////

無駄なカードが現れた時に、特定の処理を行いたい場合、例えばそのカードを "Difficult"
という名前の単語帳に移動する場合、次のようなコードで実現できます。


/////
-----
from anki.hooks import addHook
from aqt import mw

def onLeech(card):
    # can modify without .flush(), as scheduler will do it for us
    card.did = mw.col.decks.id("Difficult")
    # if the card was in a cram deck, we have to put back the original due
    # time and original deck
    card.odid = 0
    if card.odue:
        card.due = card.odue
        card.odue = 0

addHook("leech", onLeech)
-----
/////

-----
from anki.hooks import addHook
from aqt import mw

def onLeech(card):
    # スケジューラーが修正する際には、 .flush() を使わずに修正できます。
    card.did = mw.col.decks.id("Difficult")
    # カードがフィルター単語帳の中にある場合は、復習時期を元に戻して取得元の単語帳に
    # 戻さなければなりません
    card.odid = 0
    if card.odue:
        card.due = card.odue
        card.odue = 0

addHook("leech", onLeech)
-----


/////
An example of a filter is in aqt/editor.py. The editor calls the
"editFocusLost" filter each time a field loses focus, so that add-ons can
apply changes to the note:
/////

aqt/editor.py の中に 'filter' の例があります。エディターは、入力欄からフォーカスが外れる
と "editFocusLost" filter を呼び出します。そして、アドオンはノートに変更を加えます。

/////
-----
if runFilter(
    "editFocusLost", False, self.note, self.currentField):
    # something updated the note; schedule reload
    def onUpdate():
        self.loadNote()
        self.checkValid()
    self.mw.progress.timer(100, onUpdate, False)
-----
/////

-----
if runFilter(
    "editFocusLost", False, self.note, self.currentField):
    # ノートを更新して、スケジュールを再度読み込む
    def onUpdate():
        self.loadNote()
        self.checkValid()
    self.mw.progress.timer(100, onUpdate, False)
-----

/////
Each filter in this example accepts three arguments: a modified flag, the
note, and the current field. If a filter makes no changes it returns the
modified flag the same as it received it; if it makes a change it returns
True. In this way, if any single add-on makes a change, the UI will reload the
note to show updates.
/////

このサンプルでは、それぞれの filter は 3 つの引数を受け取ります。修正フラグ、ノート、現在のフィールドです。
filter が変更を加えない場合は、修正フラグは受け取った値と同じ値を返します。
変更を加えた場合は、True を返します。このようにして、どんなアドオンでも変更を加えると
ユーザーインターフェイスは、ノートを読み込み直して、更新内容を表示します。

/////
The Japanese Support add-on uses this hook to automatically generate one field
from another. A slightly simplified version is presented below:
/////

Japanese Support アドオンは、このフックを使って別のフィールドからフィールドを自動的に生成します。
単純化したものを次に示します。

/////
-----
def onFocusLost(flag, n, fidx):
    from aqt import mw
    # japanese model?
    if "japanese" not in n.model()['name'].lower():
        return flag
    # have src and dst fields?
    for c, name in enumerate(mw.col.models.fieldNames(n.model())):
        for f in srcFields:
            if name == f:
                src = f
                srcIdx = c
        for f in dstFields:
            if name == f:
                dst = f
    if not src or not dst:
        return flag
    # dst field already filled?
    if n[dst]:
        return flag
    # event coming from src field?
    if fidx != srcIdx:
        return flag
    # grab source text
    srcTxt = mw.col.media.strip(n[src])
    if not srcTxt:
        return flag
    # update field
    try:
        n[dst] = mecab.reading(srcTxt)
    except Exception, e:
        mecab = None
        raise
    return True
    
addHook('editFocusLost', onFocusLost)
-----
/////

-----
def onFocusLost(flag, n, fidx):
    from aqt import mw
    # japanese model か?
    if "japanese" not in n.model()['name'].lower():
        return flag
    # src フィールドと dst フィールドがあるか?
    for c, name in enumerate(mw.col.models.fieldNames(n.model())):
        for f in srcFields:
            if name == f:
                src = f
                srcIdx = c
        for f in dstFields:
            if name == f:
                dst = f
    if not src or not dst:
        return flag
    # dst フィールドは入力済みか?
    if n[dst]:
        return flag
    # イベントは src フィールドで発生したか?
    if fidx != srcIdx:
        return flag
    # ソーステキストを取得
    srcTxt = mw.col.media.strip(n[src])
    if not srcTxt:
        return flag
    # 欄を更新
    try:
        n[dst] = mecab.reading(srcTxt)
    except Exception, e:
        mecab = None
        raise
    return True
    
addHook('editFocusLost', onFocusLost)
-----

/////
The first argument of a filter is the argument that should be returned. In the
focus lost filter this is a flag, but in other cases it may be some other
object. For example, in anki/collection.py, _renderQA() calls the "mungeQA"
filter which contains the generated HTML for the front and back of cards.
latex.py uses this filter to convert text in LaTeX tags into images.
/////

filter の第一引数は、必ず返される引数です。このフォーカスを失った時の filter の中では、
引数はフラグですが、別のオブジェクトになる場合もあります。例えば、anki/collection.py
の中では、_renderQA() は、カードの表面と裏面用に生成した HTML を収容する "mungeQA" filter
を呼び出します。latex.py は、この filter を LaTeX タグの中のテキストを画像に変換する
のに使っています。

/////
In Anki 2.1, a hook was added for adding buttons to the editor. It can be used
like so:
/////

Anki 2.1 では、エディタにボタンを追加するフックを追加しました。次のように使います。

-----
from aqt.utils import showInfo
from anki.hooks import addHook

# cross out the currently selected text
def onStrike(editor):
    editor.web.eval("wrap('<del>', '</del>');")

def addMyButton(buttons, editor):
    editor._links['strike'] = onStrike
    return buttons + [editor._addButton(
        "iconname", # "/full/path/to/icon.png",
        "strike", # link name
        "tooltip")]

addHook("setupEditorButtons", addMyButton)
-----

/////
= Monkey Patching and Method Wrapping =
/////

= モンキーパッチとメソッドの隠蔽 =

/////
If you want to modify a function that doesn't already have a hook, it's
possible to overwrite that function with a custom version instead. This is
sometimes referred to as 'monkey patching'.
/////

フックを持っていない関数を修正したい場合には、カスタム版の関数で上書きすることが可能です。
このことを、「モンキーパッチ」を呼ぶことがあります

/////
In aqt/editor.py there is a function setupButtons() which creates the buttons
like bold, italics and so on that you see in the editor. Let's imagine you
want to add another button in your add-on.
/////

aqt/editor.py には、setupButtons() という関数があり、エディターの中にある太字ボタン、
斜字体ボタンのようなボタンを生成します。自分のアドオンに違ったボタンを追加することを考えて
みましょう。

/////
WARNING: Anki 2.1 no longer uses setupButtons(). The code below is still
useful to understand how monkey patching works, but for adding buttons to the
editor please see the setupEditorButtons hook described in the previous
section.
/////

警告: Anki 2.1 は、setupButtons() をもう使用していません。このコードは、モンキーパッチがどのように動作しているか、理解するのに役立ちますが、エディタにボタンと追加するには、前の項目で説明した setupEditorButtons フックを見てください。

/////
The simplest way is to copy and paste the function from the Anki source code,
add your text to the bottom, and then overwrite the original, like so:
/////

一番簡単な方法は、Anki のソースコードからその関数をコピーペーストして、自分のテキストを
ボタンに追加します。そして、元の関数を上書きします。次の通りです。

/////
-----
from aqt.editor import Editor
    
def mySetupButtons(self):
    <copy & pasted code from original>
    <custom add-on code>
    
Editor.setupButtons = mySetupButtons
-----
/////

-----
from aqt.editor import Editor
    
def mySetupButtons(self):
    <オリジナルからコピーペーストしたコード>
    <カスタムアドオンのコード>
    
Editor.setupButtons = mySetupButtons
-----

/////
This approach is fragile however, as if the original code is updated in a
future version of Anki, you would also have to update your add-on. A better
approach would be to save the original, and call it in our custom version:
/////

この方法は、将来の Anki のバージョンで元のコードが更新されるような場合に、自分のアドオンも
更新する必要になる問題をはらんでいます。もっと良い方法は、オリジナルの関数を保存しておいて
自分のカスタムバージョンの中で呼び出すことです。

/////
-----
from aqt.editor import Editor
    
def mySetupButtons(self):
    origSetupButtons(self)
    <custom add-on code>
    
origSetupButtons = Editor.setupButtons
Editor.setupButtons = mySetupButtons
-----
/////

-----
from aqt.editor import Editor
    
def mySetupButtons(self):
    origSetupButtons(self)
    <カスタムアドオンのコード>
    
origSetupButtons = Editor.setupButtons
Editor.setupButtons = mySetupButtons
-----

/////
Because this is a common operation, Anki provides a function called wrap()
which makes this a little more convenient. A real example:
/////

これはよく行われる処理なので、Anki では wrap() という関数を提供して、もう少し使いやすく
しています。実際の例をご紹介します。

/////
-----
from anki.hooks import wrap
from aqt.editor import Editor
from aqt.utils import showInfo
    
def buttonPressed(self):
    showInfo("pressed " + `self`)    

def mySetupButtons(self):
    # - size=False tells Anki not to use a small button
    # - the lambda is necessary to pass the editor instance to the
    #   callback, as we're passing in a function rather than a bound
    #   method
    self._addButton("mybutton", lambda s=self: buttonPressed(self),
                    text="PressMe", size=False)
    
Editor.setupButtons = wrap(Editor.setupButtons, mySetupButtons)
-----
/////

-----
from anki.hooks import wrap
from aqt.editor import Editor
from aqt.utils import showInfo
    
def buttonPressed(self):
    showInfo("pressed " + `self`)    

def mySetupButtons(self):
    # - size=False は、小さいボタンは使わない
    # - lambda は、予め設定されているメソッドの代わりに関数の中で
    #    エディタインスタンスをコールバックに渡す時に必要
    self._addButton("mybutton", lambda s=self: buttonPressed(self),
                    text="PressMe", size=False)
    
Editor.setupButtons = wrap(Editor.setupButtons, mySetupButtons)
-----

/////
By default, wrap() runs your custom code after the original code. You can pass
a third argument, "before", to reverse this. If you need to run code both
before and after the original version, you can do so like so:
/////

既定では、wrap() は元のコードの後にカスタムコードを実行します。第3引数 "before" を渡すと
これを逆転できます。元のバージョンの前と後の両方で実行する必要がある場合は、次のようにします。

/////
-----
from anki.hooks import wrap
from aqt.editor import Editor
    
def mySetupButtons(self, _old):
    <before code>
    ret = _old(self)
    <after code>
    return ret
    
Editor.setupButtons = wrap(Editor.setupButtons, mySetupButtons, "around")
-----
/////

-----
from anki.hooks import wrap
from aqt.editor import Editor
    
def mySetupButtons(self, _old):
    <オリジナルの前で実行するコード>
    ret = _old(self)
    <オリジナルの後で実行するコード>
    return ret
    
Editor.setupButtons = wrap(Editor.setupButtons, mySetupButtons, "around")
-----

/////
If you need to modify the middle of a function rather than run code before or
after it, there may a good argument for adding a hook to that function in the
original code. In these situations, please post on the support site and ask
for a hook to be added.
/////

関数の前後でコードを実行するのではなく、関数の中を修正する必要がある場合には、元のコードの
中の対象とする関数にフックを追加するのが良い方法かも知れません。このような場合には、
追加するフックについての質問をサポートサイトに投稿してください。

= Qt =

/////
As mentioned in the overview, the Qt documentation is invaluable for learning
how to display different GUI widgets.
/////

概要で話したとおり、Qt documentation は 色々な GUI ウィジェットを表示する方法を学ぶのに非常に貴重な文書です。

/////
One particular thing to bear in mind is that objects are garbage collected in
Python, so if you do something like:
/////

一つ覚えておいてほしいことは、Python ではオブジェクトはガベージコレクションされます。
次のように記述するとどうなるでしょうか。

-----
def myfunc():
    widget = QWidget()
    widget.show()
-----

/////
...then the widget will disappear as soon as the function exits. To prevent
this, assign top level widgets to an existing object, like:
/////

すると、この関数を終了するとすぐにウェジットは消えてしまいます。これを避けるには、
トップレベルのウェジットに既存のオブジェクトを割り当てます。次の通りです。

-----
def myfunc():
    mw.myWidget = widget = QWidget()
    widget.show()
-----

/////
This is often not required when you create a Qt object and give it an existing
object as the parent, as the parent will keep a reference to the object.
/////

Qt オブジェクトを作って、既存のオブジェクトを親とするときには、このことはあまり必要としません。それは、親オブジェクトが新規オブジェクトを参照し続けるからです。

/////
= Standard Modules =
/////

= 標準モジュール =

/////
Anki ships with only the standard modules necessary to run the program - a
full copy of Python is not included. For that reason, if you need to use a
standard module that is not included with Anki, you'll need to bundle it with
your add-on.
/////

Anki は、このプログラムの実行に必要な標準モジュールだけを含めて提供しています。Python
の完全な複製を含んではいません。このために、Anki が含んでいない標準モジュールを使う必要が
ある場合には、自分のアドオンに同梱する必要があります。

/////
This only works with pure Python modules - modules that require C extensions
such as numpy are much more difficult to package, as you would need to compile
them for each of the operating systems Anki supports. If you're doing something
sophisticated, it would be easier to get your users to install a standalone
copy of Python instead.
/////

この場合、pure Python モジュールは使えますが、numpy のような C 拡張を必要とするモジュールを同梱するのは非常に困難です。その理由は、Anki がサポートするオペレーティングシステム用にそれぞれコンパイルする必要があるからです。もし込み入ったことをするのであれば、代わりにユーザーに Python のスタンドアロンファイルをインストールしてもらう方が簡単です。

[[configuration]]
/////
= Configuration =
/////
= 設定 =

/////
If you include a config.json file with a JSON dictionary in it, Anki will
allow users to edit it from the add-on manager.
/////

JSON dictionary で設定を書いた config.json ファイルを入れると、ユーザーは Anki  のアドオンマネージャから編集できるようになります。

/////
A simple example: in config.json:
/////

簡単な例として、config.json に次のように記述します。 

   {"myvar": 5}

/////
In config.md:
/////

config.md は次のように記述します。

/////
  This is documentation for this add-on's configuration, in *markdown* format.
/////

  この文書はこのアドオンの設定用で、*markdown* フォーマットで書いています。

/////
In your add-on's code:
/////

アドオンのコードには次のように記述します。

    from aqt import mw
    config = mw.addonManager.getConfig(__name__)
    print("var is", config['myvar'])

/////
When updating your add-on, you can make changes to config.json. Any newly
added keys will be merged with the existing configuration.
/////

アドオンを更新する時には、config.json を変更することができます。既存の設定と新規追加のキーを統合します。

/////
If you change the value of existing keys in config.json, users who have
customized their configuration will continue to see the old values unless they
use the "restore defaults" button.
/////

config.json の中の既存のキーの値を変更する場合は、設定をカスタマイズしたユーザーが、"restore defaults" ボタンを押さない限り、古い値を使い続けることになります。

/////
If you need to programmatically modify the config, you can save your changes with:
/////

設定をプログラムで変更する必要がある場合は、次のように変更を保存します。

    mw.addonManager.writeConfig(__name__, config)

/////
NOTE: If no config.json file exists, getConfig() will return None - even if you have
called writeConfig().
/////

注意: config.json が存在しない場合は、getConfig() は None を返します。たとえ、writeConfig() を呼んでいたとしてもです。

/////
Add-ons that manage options in their own GUI can have that GUI
displayed when the config button is clicked:
/////

独自の GUI に管理オプションを持っているアドオンは、config ボタンを押した時にその GUI を表示できます。

    mw.addonManager.setConfigAction(__name__, myOptionsFunc)

ユーザーデータを外部ファイルに記録する場合は、アドオンフォルダに保存するのは避けてください。ユーザーがアドオンをアップグレードすると失われるからです。一つの代替案として、次のようにドキュメントフォルダに保存する方法があります。

/////
Avoid key names starting with an underscore - they are reserved for future use
by Anki.
/////

キー名の最初にアンダースコアを使うのを避けてください。Anki が将来利用するために予約しています。

[[userfiles]]
/////
= User Files =
/////
= ユーザーファイル =

/////
When your add-on needs configuration data other than simple keys and values,
it can use a special folder called user_files in the root of your add-on's
folder. Any files placed in this folder will be preserved when the add-on is
upgraded. All other files in the add-on folder are removed on upgrade.
/////

アドオンの設定に簡単なキーと値の組み合わせ以外のデータが必要な時は、"user_files" という名前の特別なフォルダをアドオンフォルダのルートに置いて使うことができます。このフォルダに置いたファイルはどれも、アドオンの更新時に保護します。アドオンフォルダのこれ以外のファイルは全て更新時に削除します。

/////
To ensure the user_files folder is created for the user, you can put a
README.txt or similar file inside it before zipping up your add-on.
/////

ユーザー用の "user_files" フォルダを必ず確実に作るには、アドオンを zip ファイルにする前に README.txt や 同じようなファイルをその中に置くことで可能です。

/////
When Anki upgrades an add-on, it will ignore any files in the .zip that
already exist in the user_files folder.
/////

Anki がアドオンを更新する時は、zip ファイルの中で "user_files" にすでに存在するファイルはどれも無視します。

[[reviewjs]]
/////
= Javascript in the question and answer =
/////
= 質問解答画面での JavaScript =

/////
(coming in 2.1.0beta16)
/////

(2.1.0beta16 で導入予定)

/////
Anki provides a hook to modify the question and answer HTML before it is
displayed in the review screen, preview dialog, and card layout screen. This
can be useful for adding Javascript to the card.
/////

Anki は、復習画面やプレビューダイアログ、カードレイアウト画面に質問や解答を表示する前に HTML を変更するフックを提供します。 このフックはカードに JavaScript を追加するのに役立ちます。

/////
An example:
/////
例:

    from anki.hooks import addHook
    def prepare(html, card, context):
        return html + """
    <script>
    document.body.style.background = "blue";
    </script>"""
    addHook('prepareQA', prepare)

/////
The hook takes three arguments: the HTML of the question or answer, the
current card object (so you can limit your add-on to specific note types for
example), and a string representing the context the hook is running in.
/////

このフックは三つの引数を取ります。質問または解答の HTML、現在のカードオブジェクト (これによって、例えば特定のノートタイプにアドオンを限定することができます)、フックを実行するコンテキストを示す文字列です。

/////
Make sure you return the modified HTML.
/////

変更した HTML を必ず戻すようにしてください。

/////
Context is one of: "reviewQuestion", "reviewAnswer", "clayoutQuestion",
"clayoutAnswer", "previewQuestion" or "previewAnswer".
/////

コンテキストは次の中から一つ選びます。"reviewQuestion", "reviewAnswer", "clayoutQuestion", "clayoutAnswer", "previewQuestion", "previewAnswer"

/////
NOTE: The answer preview in the card layout screen, and the previewer set to
"show both sides" will only use the "Answer" context. This means Javascript
you append on the back side of the card should not depend on Javascript that
is only added on the front.
/////

注意: カードレイアウト面での解答のプレビューや、"show both sides (両面表示)" を設定したプレビュー画面は、"Answer" コンテキストだけ使えます。これは カードの裏面に追加した Javascript は、表面だけに追加した JavaScript に依存すべきではないことを意味します。

/////
Because Anki fades the previous text out before revealing the new text,
Javascript hooks are required to perform actions like scrolling at the correct
time. You can use them like so:
/////

Anki は新しいテキストを表示する前に、前のテキストをフェードアウトするため、JavaScript のフックは、適切なタイミングでスクロールするようにアクションを実行する必要があります。次のように行います。

    from anki.hooks import addHook
    def prepare(html, card, context):
        return html + """
    <script>
    onUpdateHook.push(function () {
        window.scrollTo(0, 2000);
    })
    </script>"""
    addHook('prepareQA', prepare)

/////
- onUpdateHook fires after the new card has been placed in the DOM, but before
it is shown.
/////
- onUpdateHook は新しいカードを DOM に配置した後に発生しますが、このカードを表示する前です。
/////
- onShownHook fires after the card has faded in.
/////
- onShownHook はこのカードがフェードインした後に発生します。

/////
The hooks are reset each time the question or answer is shown.
/////

このフックは、質問や解答を表示するたびにリセットします。

/////
= Debugging =
/////

= デバッグ =

/////
If your code throws an exception, it will be caught by Anki's standard
exception handler (which catches anything written to stderr). If you need to
print information for debugging purposes, you can use aqt.utils.showInfo, or
write it to stderr with sys.stderr.write("text\n").
/////

自分のコードから例外が発生した時には、Anki の標準例外ハンドラー (標準エラー出力に書き出さ
れるものは何でも) が補足します。デバッグ目的のために、情報を出力する必要がある場合は、
aqt.utils.showInfo を使うか、sys.stderr.write("text\n") で標準エラー出力に書き出す
必要があります。

/////
Anki also includes a REPL. From within the program, press the https://apps.ankiweb.net/docs/manual.html#debug-console[shortcut key]
and a window will open up. You can enter expressions or statements into the
top area, and then press ctrl+return/command+return to evaluate them. An
example session follows:
/////

Anki には、REPL が含まれています。プログラムの中から https://apps.ankiweb.net/docs/manual.html#debug-console[shortcut key] を押すと
ウィンドウが立ち上がります。上の欄に式や文を入力し、ctrl+return/command+return を押すと
評価します。セッション例を次に挙げます。


/////
-----
>>> mw
<no output>

>>> print(mw)
<aqt.main.AnkiQt object at 0x10c0ddc20>

>>> invalidName
Traceback (most recent call last):
  File "/Users/dae/Lib/anki/qt/aqt/main.py", line 933, in onDebugRet
    exec text
  File "<string>", line 1, in <module>
NameError: name 'invalidName' is not defined

>>> a = [a for a in dir(mw.form) if a.startswith("action")]
... print(a)
... print()
... pp(a)
['actionAbout', 'actionCheckMediaDatabase', ...]

['actionAbout',
 'actionCheckMediaDatabase',
 'actionDocumentation',
 'actionDonate',
 ...]

>>> pp(mw.reviewer.card)
<anki.cards.Card object at 0x112181150>

>>> pp(card()) # shortcut for mw.reviewer.card.__dict__
{'_note': <anki.notes.Note object at 0x11221da90>,
 '_qa': [...]
 'col': <anki.collection._Collection object at 0x1122415d0>,
 'data': u'',
 'did': 1,
 'due': -1,
 'factor': 2350,
 'flags': 0,
 'id': 1307820012852L,
 [...]
}

>>> pp(bcard()) # shortcut for selected card in browser
<as above>
-----
/////

-----
>>> mw
<no output>

>>> print(mw)
<aqt.main.AnkiQt object at 0x10c0ddc20>

>>> invalidName
Traceback (most recent call last):
  File "/Users/dae/Lib/anki/qt/aqt/main.py", line 933, in onDebugRet
    exec text
  File "<string>", line 1, in <module>
NameError: name 'invalidName' is not defined

>>> a = [a for a in dir(mw.form) if a.startswith("action")]
... print(a)
... print()
... pp(a)
['actionAbout', 'actionCheckMediaDatabase', ...]

['actionAbout',
 'actionCheckMediaDatabase',
 'actionDocumentation',
 'actionDonate',
 ...]

>>> pp(mw.reviewer.card)
<anki.cards.Card object at 0x112181150>

>>> pp(card()) # mw.reviewer.card.__dict__ へのショートカット
{'_note': <anki.notes.Note object at 0x11221da90>,
 '_qa': [...]
 'col': <anki.collection._Collection object at 0x1122415d0>,
 'data': u'',
 'did': 1,
 'due': -1,
 'factor': 2350,
 'flags': 0,
 'id': 1307820012852L,
 [...]
}

>>> pp(bcard()) # ブラウザで選択したカードへのショートカット
<as above>
-----

/////
Note that you need to explicitly print an expression in order to see what it
evaluates to. Anki exports pp() (pretty print) in the scope to make it easier
to quickly dump the details of objects, and the shortcut ctrl+shift+return
will wrap the current text in the upper area with pp() and execute the result.
/////

何が評価されたか知るためには、式を明示的に出力する必要があることに注意してください。Anki では
pp() (pretty print) がスコープの中でオブジェクトの詳細を素早くダンプすることが簡単に
できるようになっています。ショートカット ctrl+shift+return は上の欄中の現在のテキストを
pp() で囲んで実行し結果を表示します。

/////
If you're on Linux or are running Anki from source, it's also possible to
debug your script with pdb. Place the following line somewhere in your code,
and when Anki reaches that point it will kick into the debugger in the
terminal:
/////

Linux を使っているかソースコードから Anki を実行している場合は、自分のスクリプトを pdb を
使ってデバッグすることも可能です。次の行を自分のコードのどこかに置けば、Anki がその場所に
達するとターミナルにデバッガーが立ち上がります。

-----
from aqt.qt import debug; debug()
-----

/////
Alternatively you can export DEBUG=1 in your shell and it will kick into the
debugger on an uncaught exception.
/////

別の方法としては、export DEBUG=1 と自分のシェルで実行すれば、補足していない例外個所で
デバッガーが立ち上がります。

/////
= Learning More =
/////

= もっと詳しく学びたい場合には =

/////
Anki's source code is available at http://github.com/dae/. The
colllection object is defined in anki's collection.py. Other useful files
to check out are cards.py, notes.py, sched.py, models.py and decks.py.
/////

Anki のソースコードは http://github.com/dae/ で入手できます。コレクション
オブジェクトは、anki の collection.py の中で定義されています。他に調べる価値のある
ファイルは、cards.py、notes.py、sched.py、models.py や decks.py です。

/////
It can also be helpful to look in the aqt source to see how it's calling
anki for a particular operation, or to learn more about the GUI.
/////

aqt のソースコード見ることも、特定の処理のための anki の呼び出し方や GUI の詳細
を理解するのに役立ちます。

/////
Much of the GUI is defined in designer files. You can use the Qt Designer
program to open the .ui files and browse the GUI in a convenient way. 
/////

多くの GUI は、designer ファイルの中で定義されてます。Qt Designer というプログラムを
使えば .ui ファイルを開いて、GUI をブラウズすることが簡単にできます。

/////
And finally, it can also be extremely helpful to browse other add-ons to see
how they accomplish something.
/////

最後になりますが、他のアドオンが何かを実現している方法を見ることも、非常に役立ちます。

[[sharing]]
/////
= Sharing Add-ons =
/////

= アドオンの共有 =

/////
AnkiWeb expects a .zip file of the contents of an add-on module, without
the folder name. For example, if you have a module like the following:
/////

AnkiWeb は、アドオンモジュールを収録するには .zip ファイルを要求します。フォルダ名は必要しとません。例えば、次のようなモジュールを持っているとします。

  addons21/myaddon/__init__.py
  addons21/myaddon/my.data

/////
Then the zip file contents should be:
/////

この場合、zip ファイルの内容を次のようにしてください。

  __init__.py
  my.data

/////
If you include the folder name in the zip like the following, AnkiWeb will not
accept the zip file:
/////

フォルダ名を含めた次のような zip ファイルは、AnkiWeb は受け付けません。

 myaddon/__init__.py
 myaddon/my.data

/////
You can give the .zip file any name.
/////

.zip ファイルの名前は自由に付けることができます。

/////
Python automatically creates `__pycache__` folders when your add-on is run.
Please make sure you delete these prior to creating the zip file, as AnkiWeb
can not accept .zip files that contain `__pycache__` folders.
/////

Python は、実行するときに `__pycache__` フォルダを自動的に作ります。zip を作る前に必ずこのフォルダを削除してください。AnkiWeb は、`__pycache__` フォルダを含んだ .zip ファイルを受け付けないからです。

/////
You can upload a .zip you've created to https://ankiweb.net/shared/addons/
/////

 .zip ファイルを作ったら https://ankiweb.net/shared/addons/ にアップロードできます。

/////
= Porting Anki 2.0 add-ons =
/////

= Anki 2.0 アドオンの移植 =

Python 3
--------

/////
Anki 2.1 requires Python 3.6 or later. After installing Python 3 on your
machine, you can use the 2to3 tool to automatically convert your existing
scripts to Python 3 code on a folder by folder basis, like:
/////

Anki 2.1 は Python 3.6 以降が必須です。Python 3 を自分のマシンにインストールしたら、2to3 ツールを使って、自動的に既存のスクリプトを Python 3 のコードにフォルダ単位で変換できます。 次の通りです。

  2to3-3.6 --output-dir=aqt3 -W -n aqt
  mv aqt aqt-old
  mv aqt3 aqt

/////
Most simple code can be converted automatically, but there may be parts of the
code that you need to manually modify.
/////

ほとんどの単純なコードは自動的に変換できますが、手作業で変更の必要がある箇所が残るかもしれません。

Qt5 / PyQt5
----------

/////
The syntax for connecting signals and slots has changed in PyQt5. Recent PyQt4
versions support the new syntax as well, so the same syntax can be used for
both Anki 2.0 and 2.1 add-ons.
/////

PyQt5 でシグナルとスロットをつなぐ構文が変わりました。最近の PyQt4 バージョンではこの新しい構文を同じようにサポートしていますので、Anki 2.0 と 2.1 の両方のアドオンで同じ構文を使えます。

/////
More info is available at
/////
さらに詳しい情報は次のリンクをご覧ください。
http://pyqt.sourceforge.net/Docs/PyQt4/new_style_signals_slots.html

/////
One add-on author reported that the following tool was useful to automatically
convert the code:
/////
あるアドオン作者が次のツールがコードを自動的に変換するのに役立ったと報告してくれました。
https://github.com/rferrazz/pyqt4topyqt5

/////
The Qt modules are in 'PyQt5' instead of 'PyQt4'. You can do a conditional
import, but an easier way is to import from aqt.qt - eg
/////

Qt モジュールは、'PyQt4' の代わりに 'PyQt5' の中にあります。条件分岐で読み込むこともできますが、さらに簡単な方法は aqt.qt から読み込むことです。例えば次のようにします。

  from aqt.qt import *

/////
That will import all the Qt objects like QDialog without having to specify the
Qt version.
/////

これは、特定の Qt のバージョンを指定することなく、QDialog のような全ての Qt オブジェクトを読み込みます。

/////
Single .py add-ons need their own folder
/////
単一の .py アドオンにも独自のフォルダが必要
------------------------

/////
Each add-on is now stored in its own folder. If your add-on was previously
called `demo.py`, you'll need to create a `demo` folder with an `__init__.py` file.
/////

それぞれのアドオンは、独自のフォルダに保存することになりました。以前 `demo.py` という名前をつけていたアドオンの場合、`demo` というフォルダと、`__init__.py` を一緒に作る必要あります。

/////
If you don't care about 2.0 compatibility, you can just rename `demo.py` to
`demo/__init__.py`.
/////

2.0 との互換性を気にしないなら、名前を `demo.py` を `demo/__init__.py` に変更するだけで済みます。

/////
If you plan to support 2.0 with the same file, you can copy your original file
into the folder (`demo.py` -> `demo/demo.py`), and then import it relatively
by adding the following to `demo/__init__.py`:
/////

同じファイルで 2.0 をサポートする計画の場合は、元のファイルをフォルダにコピーして (`demo.py` -> `demo/demo.py`)、さらに次のような `demo/__init__.py` を追加して、相対的にアドオンを読み込みます。

    from . import demo

/////
The folder needs to be zipped up when uploading to AnkiWeb. For more info,
please see <<sharing,sharing add-ons>>.
/////

AnkiWeb にアップロードする時にはフォルダを Zip ファイルに収める必要があります。さらに詳しい情報は <<sharing,アドオンの共有>> をご覧ください。

/////
Folders are deleted when upgrading
/////
アップグレードでフォルダを削除
--------------

/////
When an add-on is upgraded, all files in the add-on folder are deleted. The
only exception is the special <<userfiles,user_files folder>>. If your add-on
requires more than simple key/value configuration, make sure you store the
associated files in the user_files folder, or it will be lost on upgrade.
/////

アドオンを更新する時には、アドオンフォルダのすべてのファイルを削除します。例外は特別な <<userfiles,user_files フォルダ>> だけです。アドオンが単純なキー/値の組み合わせ以外の設定データが必要な場合は、必ず関連するファイルを "user_files" に保存して、更新時に失われるのを避けてください。

/////
Supporting both 2.0 and 2.1 in one codebase
/////
2.0 と 2.1 を一つのコードベースでサポート
------------------------

/////
Most Python 3 code will run on Python 2 as well, so it is possible to update
your add-ons in such a way that they run on both Anki 2.0 and 2.1. Whether
this is worth it depends on the changes you need to make.
/////

ほとんどの Python 3 のコードは、Python 2 でも動作します。このため、Anki 2.0 と 2.1 の両方で動作するようにアドオンを更新することが可能です。このようにする価値があるかどうかは、必要のある変更内容によります。

/////
Most add-ons that affect the scheduler should require only minor changes to
work on 2.1. Add-ons that alter the behaviour of the reviewer, browser or
editor may require more work.
/////

scheduler に手を加えているほとんどのアドオンは、わずかな変更だけで 2.1 で動作するでしょう。reviewer、browser、editor の動作を変更するアドオンはさらに多くの作業を必要とします。

/////
The most difficult part is the change from the unsupported QtWebKit to
QtWebEngine. If you do any non-trivial work with webviews, some work will be
required to port your code to Anki 2.1, and you may find it difficult to
support both Anki versions in the one codebase.
/////

最も困難な箇所は、サポートを停止した QtWebKit から QtWebEngine への変更です。WebView を使って単純ではない操作をしている場合は、Anki 2.1 へのコードの移植は、ある程度の作業が必要になり、一つのコードベースで両方のバージョンの Anki をサポートするのは難しいと考えるかもしれません。

/////
If you find your add-on runs without modification, or requires only minor
changes, you may find it easiest to add some if statements to your code and
upload the same file for both 2.0.x and 2.1.x.
/////

修正なしにアドオンが動作する場合、あるいはわずかな変更が必要な場合には、if 文をコードに追加して、同じファイルで 2.0.x と 2.1.x の両方をサポートするファイルをアップロードするのが一番簡単かもしれません。

/////
If your add-on requires more significant changes, you may find it easier to
stop providing updates for 2.0.x, or to maintain separate files for the two
Anki versions.
/////

もっと大きい変更が必要な場合は、2.0.x に対する更新を停止し、あるいは別のファイルで二つのバージョンをサポートすることを維持するのがより簡単かもしれません。

/////
Webview Changes
/////
Webview の変更点
----------------

/////
Qt 5 has dropped WebKit in favour of the Chromium-based WebEngine, so
Anki's webviews are now using WebEngine. Of note:
/////

Qt 5 は、WebKit の代わりに Chromium ベースの WebEngine を採用しました。このため、Anki の WebView には、WebEngine を現在使用しています。そのためのノートです。

/////
- You can now debug the webviews using an external Chrome instance, by setting
  the env var QTWEBENGINE_REMOTE_DEBUGGING to 8080 prior to starting Anki,
  then surfing to localhost:8080 in Chrome.
/////
- 外部の Chrome インスタンスを使って WebView をデバッグできるようになりました。Anki を起動する前に環境変数 QTWEBENGINE_REMOTE_DEBUGGING を 8080 に設定して、Chrome で localhost:8080 にアクセスします。
/////
- WebEngine uses a different method of communicating back to Python.
  AnkiWebView() is a wrapper for webviews which provides a pycmd(str) function in
  Javascript which will call the ankiwebview's onBridgeCmd(str) method. Various
  parts of Anki's UI like reviewer.py and deckbrowser.py have had to be
  modified to use this.
/////
- WebEngine は Python との通信に別の方法を使います。
  AnkiWebView() は、WebView 用のラッパーで pycmd(str) 関数を提供します。この関数は Javascript の中で ankiwebview の onBridgeCmd(str) メドッドを呼び出します。 Anki の UI の reviewer.py や deckbrowser.py といった様々な場所で、これを使うために変更しなければなりませんでした。
/////
- Javascript is evaluated asynchronously, so if you need the result of a JS
  expression you can use ankiwebview's evalWithCallback().
/////
- Javascript を非同期的に評価します。このため、JS の式の結果が必要な場合は ankiwebview の evalWithCallback() を使うことができます。
/////
- As a result of this asynchronous behaviour, editor.saveNow() now requires a
  callback. If your add-on performs actions in the browser, you likely need to
  call editor.saveNow() first and then run the rest of your code in the callback.
  Calls to .onSearch() will need to be changed to .search()/.onSearchActivated()
  as well. See the browser's .deleteNotes() for an example.
/////
- この非同期の動作の結果、editor.saveNow() はコールバックが必要になりました。アドオンがブラウザ内でアクションを実行する場合、editor.saveNow() を最初に呼んでから、コールバックの中のコードの残りを実行する必要がおそらくあるでしょう。
  .onSearch() を呼ぶには、.search()/.onSearchActivated() も変更する必要があります。例えば、ブラウザの .deleteNotes() をご覧ください。
/////
- Various operations that were supported by WebKit like setScrollPosition() now
need to be implemented in javascript.
/////
- setScrollPosition() のような WebKit でサポートした様々な操作は、JavaScript で実装する必要があります。
/////
- Page actions like mw.web.triggerPageAction(QWebEnginePage.Copy) are also
asynchronous, and need to be rewritten to use javascript or a delay.
/////
- mw.web.triggerPageAction(QWebEnginePage.Copy) のようなページの動作も非同期で、JavaScript や遅延を使って書き直す必要があります。
/////
- WebEngine doesn't provide a keyPressEvent() like WebKit did, so the code
that catches shortcuts not attached to a menu or button has had to be changed.
setStateShortcuts() fires a hook that can be used to adjust the shortcuts for
a given state.
/////
- WebEngine には、WebKit のような keyPressEvent() を提供していません。このため、メニューやボタンに割り当ててないショートカットを捕捉するコードは変更しなければなりませんでした。setStateShortcuts()  は、指定した状態のショートカットを調節するのに使えるフックを呼び出します。

/////
Reviewer Changes
/////
Reviewer の変更点
----------------

/////
Anki now fades the previous card out before fading the next card in, so the
next card won't be available in the DOM when the showQuestion hook fires.
There are some new hooks you can use to run Javascript at the appropriate time
- see <<reviewjs,here>> for more.
/////

Anki は次のカードをフェードインする前に、前のカードをフェードアウトするようになりました。このため showQuestion フックが発生した時には、DOM の中の次のカードが表示できません。適切な時に Javascript を実行するのに使える新しいフックがあります。詳しくは、<<reviewjs,こちら>> をご覧ください。

/////
Add-on Configuration
/////
アドオンの設定
---------

/////
Many small 2.0 add-ons relied on users editing the sourcecode to customize them. This is no longer a good idea in 2.1, because changes made by the user will be overwritten when they check for and download updates. 2.1 provides a <<configuration>> system to work around this. If you need to continue supporting 2.0 as well, you could use code like the following:
/////

多くの小さな 2.0 用のアドオンは、ユーザーがソースコードを編集してカスタマイズすることを必要としていました。2.1 では、これはもう良いアイデアではありません。ユーザーの変更が、更新の確認やダウンロードで上書きされるからです。2.1 では <<configuration,設定>> システムを導入して、このような場合に対応するようになりました。2.0 も同様にサポートする必要がある場合には、次のようなコードが使えるでしょう。

  if getattr(mw.addonsManager, "getConfig", None):
      config = mw.addonManager.getConfig(__name__)
  else:
      config = dict(optionA=123, optionB=456)