lod-anki

lod-anki is a command line tool that allows you to import data from the Luxembourger Dictionary Online (LOD) into Anki, a popular open-source flashcard program. With this library, you can create personalized flashcards from LOD dataset, enabling efficient learning and retention of information.

Features

• Import data from LOD.lu into Anki decks, with pronunciations and examples.
• Map noun, verb, preposition, conjunction, adjective, adverb, and numeral to words dataset.
• Export words into Anki flashcards, from a plain word list or a JSON deck file.

Quick start

You don't need to be a programmer. You need about 5 minutes and a terminal (the "Terminal" app on macOS, "PowerShell" on Windows).

1. Install Node.js

Download the LTS version from nodejs.org and install it like any other app. To check it worked, open a new terminal and run:

node -v

It should print a version number such as v22.12.0 or newer. lod-anki needs Node.js 22.12 or later.

2. Write your word list

Create a folder for your decks, for example lux-decks in your home folder. In it, create a plain text file named greetings.txt with the words you want to learn, one per line:

Äddi
Moien

Write words in lowercase, except nouns, which start with a capital letter as in Luxembourgish. Blank lines and lines starting with # are ignored.

3. Create the Anki deck

In the terminal, go to your folder and run lod-anki:

cd lux-decks
npx lod-anki export greetings.txt

npx downloads and runs lod-anki for you, so there is nothing to install globally. This creates greetings_english.apkg. Double-click it (or use File > Import in Anki) to add the deck.

Cards are in English unless you choose other languages, and the deck is named after the file unless you pass --name:

npx lod-anki export greetings.txt --languages EN,FR --name "Greetings"

For more control, such as filtering by word type or exporting a whole CEFR level, use a deck file instead.

The first export downloads the LOD data (about 20 MB) and keeps it in your user cache folder (~/.cache/lod-anki on Linux, ~/Library/Caches/lod-anki on macOS, %LOCALAPPDATA%\lod-anki on Windows). Pronunciations are downloaded from lod.lu the first time a word is exported and kept there too, so you need an internet connection when you export.

The data is rebuilt every month from the LOD linguistic dataset published by the Zenter fir d'Lëtzebuerger Sprooch (CC0). Run npx lod-anki update to get the latest data.

Re-importing a deck you exported again later updates the existing cards in Anki instead of adding duplicates, so your review progress is kept.

Ready-made decks

Just want to start learning? Download a deck and double-click it to import it into Anki. Each one comes in four card languages:

| Deck | Download | | --- | --- | | Every LOD word of level A1 | English · French · German · Portuguese | | Every LOD word of level A2 | English · French · German · Portuguese | | Every LOD word (32,000+), tagged by level and topic; pronunciations stream from the internet | English · French · German · Portuguese | | Schwätzt dir Lëtzebuergesch? A1 | English · French · German · Portuguese | | Schwätzt dir Lëtzebuergesch? A2 | English · French · German · Portuguese | | Schwätzt dir Lëtzebuergesch? B1 | English · French · German · Portuguese | | Schwätzt dir Lëtzebuergesch? A1 to B1 | English · French · German · Portuguese |

In the all-words deck, use Anki's browser to study a subset, for example tag:A1 or tag:LOD::Topic::Food. Topic, word-type and register tags are in the deck's language (LOD::Thème::Nourriture, LOD::Nature::Verbe and LOD::Registre::Familier in the French deck) and appear as a tree in Anki's sidebar. Its pronunciations play only while you are online, which keeps the deck small (about 8 MB).

Decks by word type (nouns, verbs, adjectives, adverbs) are on the lod-data release too. They are rebuilt every month with the latest LOD data.

Commands

| Command | Description | | --- | --- | | export <deck> | Creates one .apkg file per language from a word list (.txt, one word per line) or a deck file (.json). | | update | Downloads the latest LOD data. | | extract <lodDump> | Builds the data yourself from the LOD XML dump into <output>/lod. |

Options

| Option | Description | | --- | --- | | -d, --data <directory> | Use LOD data from this folder instead of the downloaded one, for example a lod.zip you extracted yourself. A lod folder next to where you run lod-anki is also picked up. | | -o, --output <directory> | Where to write the .apkg files. Defaults to the current folder. | | -l, --languages <codes> | export only. Card languages, comma separated: ALL (German), EN, FR, PO (Portuguese). Defaults to the deck file's languages, or EN for a word list. | | -n, --name <name> | export only. The deck name shown in Anki. Defaults to the deck file's name, or the word list's file name. | | -a, --audio <mode> | export only. offline (default) puts the pronunciations in the deck. online streams them while you review, so the deck is much smaller but needs internet. Example sentences have a 🔈 button that plays their recording, bundled in offline decks and streamed in online ones. With ffmpeg installed, offline decks bundle the recordings as small mp3 files, about a third of their size. |

For example: npx lod-anki export deck.json --data ~/Downloads/lod. Set the LOD_ANKI_CACHE environment variable to keep the downloaded data somewhere else.

Troubleshooting

• Could not download the LOD data: check your internet connection. You can also download lod.zip yourself, extract it, and pass --data <path/to/lod>.
• LOD data not found: the folder given with --data has no words folder. Point it at the extracted lod folder.
• <word> not found!: that word is not in the LOD data. Check the spelling and capitalisation (nouns start with a capital letter).

Prefer a global install?

npm install -g lod-anki
lod-anki export greetings.txt

If this fails with EACCES: permission denied, your npm is not allowed to write to its global folder. Use npx as above, or install Node.js through a version manager such as nvm, which avoids the problem.

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvement, please open an issue or submit a pull request. Make sure to follow the existing code style and include appropriate tests.

License

This project is licensed under the GPL v3 License.

HOWTO

How to build a deck file?

The deck file is a JSON file, with the following schema:

• name: It is the name of the deck, shown in Anki. It will be concatenated with the language, to avoid duplicity, if you want to export multiple languages;
• fileName: It is the file name. It will be concatenated with the language, to avoid duplicity;
• flashcards: The collection of words in Luxembourgish you want to export. Optional when you use categories;
• languages: The collection of languages you want to export to. The possible values are: ALL (German), EN (English), FR (French), and PO (Portuguese);
• types: The collection of word types you want to export. lod-anki will filter the flashcards (or words), and export only the ones matching the types in this list. This field is optional. noun, verb, preposition, conjunction, adjective, adverb, and numeral are supported by this tool.
• categories: LOD categories to export, such as CEFR levels (A1, A2, B1, ...) or topics (FAMILL for family, ...). This field is optional. Without flashcards, the deck holds every word in these categories; with flashcards, only the listed words in these categories are kept. Cards are tagged with their word type, CEFR level and topic in Anki; word-type and topic tags are in the deck language, such as LOD::Word_type::Noun and LOD::Topic::Family for FAMILL. Words with colloquial, vulgar or other marked examples also get a register tag, such as LOD::Register::Colloquial.
• allWords: Set to true to export every LOD word. This field is optional.
• audio: offline (default) puts the pronunciations in the deck; online streams them from the lod-anki audio mirror, so the deck is small but needs internet while reviewing. This field is optional.

Below you can see an example:

{
    "name": "Greeting in Luxembourgish",
    "fileName": "greeting_in_luxembourgish",
    "flashcards": [
        "Äddi",
        "Awar",
        "Awuer",
        "Bonjour",
        "Moien"
    ],
    "languages": [
        "ALL",
        "EN",
        "FR",
        "PO"
    ]
}

A deck with all A1 words needs no word list:

{
    "name": "Luxembourgish A1",
    "fileName": "luxembourgish_a1",
    "categories": ["A1"],
    "languages": ["EN"]
}

If such a deck comes out empty, run npx lod-anki update to download LOD data that includes categories.

When building the deck, put the words in lowercase. But if it is a noun, capitalize the first character, as it is in Luxembourgish.

Releasing

1. Bump the version in a pull request: npm version patch|minor|major --no-git-tag-version, then commit package.json and package-lock.json.
2. After it is merged, open Actions › Publish to npm › Run workflow on main. It tags the version from package.json, creates the GitHub release, and stages the package on npm. It stops if that version is already released.
3. Approve the staged version on npmjs.com (or with npx npm@latest stage approve <id>) to make it live.