add2anki — add language study cards to Anki

A CLI tool to add language learning cards to Anki, with automatic translation and audio generation.

Currently supports English to Mandarin Chinese translation with audio generation using two providers:

• Google Translate TTS (default, no authentication required)
• ElevenLabs (requires API key)

For related language learning resources, visit Oliver Steele's Language Learning Resources.

Features

• 🔄 Translate English text to Mandarin Chinese using OpenAI's GPT models
• 🗣️ Support for different translation styles:
  • conversational (default): Natural, everyday language
  • formal: More polite expressions appropriate for business or formal situations
  • written: Literary style suitable for written texts
• 🔊 Generate high-quality audio for Chinese text using one of two providers:
  • Google Translate TTS (default, no authentication required)
  • ElevenLabs (requires API key)
• 🃏 Add cards to Anki with translation and audio
• 🏷️ Add custom tags to notes or use the default "add2anki" tag
• 🧠 Context-aware language detection that automatically identifies languages
• 🔍 Automatic detection of suitable note types and field mappings
• 🔧 Support for custom note types with field name synonyms (Hanzi/Chinese, Pinyin/Pronunciation, English/Translation)
• 💾 Configuration saved between sessions
• 📚 Support for batch processing from text, CSV/TSV, or SRT subtitle files
• 🎬 Parse SRT files to create cards from Mandarin subtitles
• 🤔 Interactive mode for adding cards one by one

Prerequisites

• Python 3.11 or higher
• Anki with the AnkiConnect plugin installed
• OpenAI API key
• For audio generation (optional, as Google Translate is used by default):
  • ElevenLabs API key (for ElevenLabs)

Installation

You can install add2anki using either uv, or pipx, or pip:

Using uv

1. Install uv if you don't have it already.

2. Install add2anki:

uv tool install add2anki

Using pipx

1. Install pipx if you don't have it already.

2. Install add2anki

pipx install add2anki

Using pip (not recommended)

This method doesn't require a third-party tool, but it is not recommended as it will install add2anki in the current Python environment, which may cause conflicts with other packages.

pip install add2anki

Environment Variables

Set the following environment variables:

# Required for translation
export OPENAI_API_KEY=your_openai_api_key

# Required only if using ElevenLabs
export ELEVENLABS_API_KEY=your_elevenlabs_api_key

Quick Start

# Basic usage (uses Google Translate TTS by default)
add2anki "Hello, how are you?"

# Start interactive mode
add2anki

Documentation

• Command Line Reference - Detailed usage and options
• Development Guide - Information for contributors

Note Type and Deck Selection

add2anki will automatically detect suitable note types in your Anki collection. A suitable note type must have fields that match:

• Hanzi/Chinese/Characters for the Chinese characters
• Pinyin/Pronunciation/Reading for the pronunciation
• English/Translation/Meaning for the English translation

If multiple suitable note types are found, you'll be prompted to select one.

Similarly, if no deck is specified via the --deck option and no previously selected deck is found in the configuration, add2anki will display a list of available decks and prompt you to select one.

Your selections for both note type and deck will be saved for future use.

Configuration

add2anki saves your preferences (deck name, note type, field mappings) in a configuration file:

• On Windows: %APPDATA%\add2anki\config.json
• On macOS/Linux: ~/.config/add2anki/config.json

Acknowledgements

This project relies on several excellent libraries:

• click for building the command-line interface
• rich for beautiful text formatting
• pydantic for robust data validation
• requests for making HTTP requests

Services:

• openai for transcription and translation
• elevenlabs for audio generation

Related Projects

• audio2anki - Tool to extract foreign language vocabulary from audio transcriptions and add to Anki
• fast-langdetect - Local language detection for multilingual text

License

MIT

Author

Oliver Steele (@osteele)