Translate Gate for Anki

An Anki add-on that fills a field with an AI translation from the API of your choice:

• When you add a note to a configured deck, the source field is translated into the target field.
• In the Browser, Notes > Translate Selected Notes (Ctrl+Shift+T, also in the right-click menu) translates the selected notes.

Built-in providers: DeepL, Google Cloud Translation and LibreTranslate (public or self-hosted). Others can be added as custom provider.

It should work with Anki 2.1.50 and later.

Features

• Pick the translation API, and give it an API key if it needs one.
• Separate mappings per deck (subdecks included if you want), each with its own fields and languages.
• Removes HTML, [sound:...] tags and furigana (漢字[かんじ]) before translating.
• Keeps cloze deletions ({{c1::...}}, including hints) working in the translation, with any provider that keeps tags intact.
• Network calls run in the background, so Anki stays responsive. Changes can be undone with Edit > Undo.
• Does not overwrite fields that already have text unless you ask it to.

Setup

1. Get an API key

Depending on the provider you want:

• DeepL: sign up for a DeepL API plan at https://www.deepl.com/pro-api (the entry plan currently comes with a one-time credit of 1 million characters), then copy your key from API Keys. Keys ending in :fx use DeepL's free endpoint automatically, all others the paid one. If DeepL tells you to use a different endpoint, set api_url.
• Google: create a Google Cloud project, enable the Cloud Translation API, and create an API key under APIs & Services > Credentials.
• LibreTranslate: self-host it (no key needed) or get a key for libretranslate.com.
• Custom: whatever the API you use requires, if anything.

2. Install

From a release file: double-click translate_gate.ankiaddon, or in Anki go to Tools > Add-ons > Install from file….

From source:

./build.sh          # runs the tests and creates dist/translate_gate.ankiaddon

Or copy the translate_gate/ folder into your Anki add-ons folder (Tools > Add-ons > View Files) and restart Anki.

3. Configure

Open Tools > Add-ons, select Translate Gate, and click Config:

{
    "provider": "deepl",
    "api_key": "your-key-here:fx",
    "mappings": [
        {
            "deck": "Japanese",
            "source_field": "Sentence",
            "target_field": "Translation",
            "source_lang": "JA",
            "target_lang": "EN-US"
        }
    ]
}

provider is one of deepl, google, libretranslate or custom. Each mapping has its own source_lang and target_lang; use the codes your provider expects (EN-US for DeepL, en for Google and LibreTranslate).

To use any other API, set provider to custom and describe the request in custom_api. For example, MyMemory, with "source_lang": "ja" and "target_lang": "en" in the mapping:

"provider": "custom",
"custom_api": {
    "url": "https://api.mymemory.translated.net/get",
    "method": "GET",
    "body": {"q": "{text}", "langpair": "{source_lang}|{target_lang}"},
    "response_path": "responseData.translatedText"
}

The config dialog lists every option next to the editor and more examples. The same text is in translate_gate/config.md.

Privacy

The text of the configured source field is sent to the API you configure to be translated. Nothing else from your collection is sent. How that text is handled depends on the provider and your plan, so read its privacy policy before translating anything sensitive. Your API key is stored in your Anki profile's add-on config, never in the add-on code, and is only sent to the configured API.

Development

The logic that does not need Anki lives in the translate_gate/core/ package:

• config.py: config dataclasses and parsing with defaults
• text.py: field HTML to plain text (tags, furigana) and back
• cloze.py: keeping clozes intact through translation
• planning.py: deck mappings and deciding which notes to translate
• providers.py: DeepL, Google, LibreTranslate and custom APIs
• translate.py: sending requests with retries and batching

It is tested with pytest:

python3 -m pytest tests

With Nix and direnv, direnv allow provides Python, pytest and ruff (see flake.nix).

translate_gate/__init__.py only contains the Anki hooks, the Browser menu entry and the threading.

Releasing

CI (.forgejo/workflows/build.yml) runs the tests and builds the add-on on every push. To release, push a version tag:

git tag v1.1.0 && git push origin v1.1.0

CI then creates a Codeberg release with translate_gate-v1.1.0.ankiaddon attached, with 1.1.0 as the version shown in Anki's add-on manager. The version is not stored anywhere in the repo. Upload that file on the add-on's AnkiWeb page; AnkiWeb has no public upload API, so this step is manual.

AI disclaimer

Parts of this add-on were written with the help of an AI coding assistant.

License

MIT, see LICENSE.