Anki Deck Builder

A Rust CLI tool that automatically creates language learning decks for Anki.

Automatically generate Anki flashcard decks with the most frequently used words in your target language, paired with translations in your native language.

🇦🇷 → 🇭🇷 Spanish to Croatian language learning

Downloads Croatian word frequency data from Hermit Dave's FrequencyWords repository, then selects the top 100 most frequent words from each part of speech (nouns, verbs, adjectives, etc.), and creates Anki flashcards with Spanish translations.

Default: 100 words × 8 parts of speech = 800 words → 1,600 bidirectional cards

---

Features

• 🎯 Automatic deck generation - Create full Anki decks with one command
• 🔄 Bidirectional cards - Practice both recognition and production (default)
• � Frequency-based - Learn the most common words first
• 🔤 Organized by grammar - Words categorized by part of speech
• 🌐 Auto-translation - Powered by LibreTranslate API
• 💾 Smart caching - Fast repeat runs, works offline
• 🎨 Beautiful CLI - Interactive prompts with progress indicators

---

Quick Start

Prerequisites (NixOS)

# Enter development environment (includes Rust and Anki)
nix-shell

# Or use direnv for automatic activation
direnv allow

Prerequisites (Other Systems)

1. Install Rust
2. Install Anki Desktop

Install AnkiConnect

In Anki:

1. Tools → Add-ons → Get Add-ons
2. Enter code: 2055492159
3. Restart Anki

Detailed setup guide →

---

Usage

Test Connection

make run ARGS="test"

Create a Deck

Interactive mode (recommended):

make run ARGS="create"

The CLI will prompt you for:

• Target language (language to learn)
• Base language (your known language)
• Deck name

Command-line mode:

# Create bidirectional deck (default - 90 cards: 45 words × 2 directions)
make run ARGS="create -t hr -b es"

# Create unidirectional deck (45 cards: Croatian→Spanish only)
make run ARGS="create -t hr -b es --bidirectional=false"

# Customize word count
make run ARGS="create -t hr -b es --words-per-pos 50"

# Custom deck name
make run ARGS="create -t hr -b es -d 'My Vocabulary'"

# Test configuration without creating
make run ARGS="create --dry-run"

---

Example Session

$ make run ARGS="create -t Croatian -b Spanish"

🚀 Anki Deck Builder - Language Learning Deck Creator

📊 Loading Croatian word frequency data...
✅ Loaded Croatian word data (45 words)

🌐 Translating 45 words from Croatian to Spanish...
[========================================] 45/45 (100%)
✅ Translation complete

📚 Creating Anki deck...
✅ Connected to AnkiConnect
✅ Created deck: 'Croatian → Spanish (Top 800 Words)'

📝 Adding 45 cards to deck...
[========================================] 45/45 (100%)
✅ Cards added

🎉 Deck creation complete!
  ✅ 45 cards added successfully
  📚 Deck: Croatian → Spanish (Top 800 Words)

💡 Open Anki to start studying!

---

Card Format

Bidirectional Cards (Default)

By default, creates 2 cards per word for comprehensive learning:

Card 1 - Recognition: Croatian → Spanish

• Front: dan
• Back: día (Noun)
• You see Croatian and recall the Spanish meaning

Card 2 - Production: Spanish → Croatian

• Front: día
• Back: dan (Noun)
• You see Spanish and produce the Croatian word

Unidirectional Cards

Use --bidirectional=false for recognition-only (Croatian → Spanish):

• Front: dan
• Back: día (Noun)

---

Configuration

Environment Variables

# Optional: Custom AnkiConnect URL (default: http://localhost:8765)
export ANKICONNECT_URL="http://localhost:8765"

# Optional: Custom LibreTranslate server
export LIBRETRANSLATE_URL="https://libretranslate.com"

View Configuration

make run ARGS="config --show"

Cache Location

Data is cached in ~/.local/share/anki-deck-builder/:

• frequency/ - Word frequency lists
• translations/ - Translated words

Clear cache:

rm -rf ~/.local/share/anki-deck-builder/

---

Development

Build & Test

# Show all available commands
make help

# Build
make build              # Debug mode
make build-release      # Release mode

# Test
make test               # Run unit tests
make check              # Quick compile check

# Code quality
make fmt                # Format code
make-lint               # Run linter
make dev                # Run all checks

Project Structure

anki-deck-builder/
├── src/
│   ├── cli.rs               # CLI interface
│   ├── ankiweb/             # AnkiConnect client
│   └── language/            # Translation & frequency data
├── tests/                   # Integration tests
├── docs/                    # Documentation
├── Makefile                 # Development commands
└── shell.nix                # NixOS environment

---

Supported Languages

Serbo-Croatian variants: Croatian, Serbian, Bosnian, Montenegrin Other languages: Spanish, English, French, German, Italian, Portuguese, Ukrainian, Japanese, Korean, Chinese, Arabic, Hindi, Dutch, Polish, Swedish, Norwegian, Danish, Finnish, Greek, Turkish

Note: Full frequency data currently available for Croatian. Other Serbo-Croatian variants and languages have basic support and may use simplified word lists or require additional data sources.

---

Troubleshooting

"Failed to connect to AnkiConnect"

1. Make sure Anki is running
2. Verify AnkiConnect is installed (code: 2055492159)
3. Test with: make run ARGS="test"

Complete troubleshooting guide →

"Translation failed"

• Requires internet connection for first run
• Subsequent runs use cached translations
• Try again if API is temporarily unavailable

"Cards failed (may be duplicates)"

This is normal if you've run the tool multiple times. Anki prevents duplicate cards. Use a different deck name or delete the existing deck first.

---

Documentation

User Guides:

• User Guide - Complete usage manual
• AnkiConnect Setup - Installation & troubleshooting

Developer Docs:

• Project Complete - Project summary and statistics
• Project Plan - Technical architecture

---

Future Enhancements

• Expand word datasets (800+ words)
• External data sources (Leipzig Corpora)
• Audio pronunciation
• Example sentences
• Image support
• More language pairs
• DeepL API integration

---

License

MIT License

Contributing

Contributions welcome! The project has a modular architecture that's easy to extend.

---

Built with: Rust 2021 | Dependencies: Tokio, reqwest, clap, dialoguer, indicatif
Platforms: Linux, macOS, Windows (via rustls-tls)