Flywheel

Your own Duolingo without overengineering

Hi, my name is Mikhail Emelyanov, I’m a Python programmer and I would like to show you my pet project — Flywheel, a micro-platform for learning foreign languages, a mixture of Duolingo and Anki, an application that can teach you to properly write in Spanish (or any other language you’re studying). Flywheel’s source code is available on GitHub.

As you may know, generalized knowledge of a foreign language can be broken down into four relatively independent components: reading, writing, listening, and speaking. Unfortunately, training one of these abilities has no direct effect on the other components, so, for example, by developing our reading skills, the effect on our writing skills is quite indirect. Flywheel is a ‘sharpener’ specifically for written Spanish.

If you’ve ever used Duolingo, you should have some idea of the format in which you’ll be studying. The formula is simple: here’s a phrase, translate it into the other language; the app will remember the last time you translated a phrase and how successful you were at it; and depending on the accuracy of your answer, it will determine when you should do the same phrase again. In my opinion, Duolingo and its approach are brilliant. However... There are certain aspects that somewhat spoil the learning experience, and Flywheel was specifically designed to address them.

Wish List

First and most importantly, I want all translation assignments to be English to Spanish only. I only want to see English phrases that I need to translate into Spanish. I don’t want to translate from Spanish to English. I’m not studying to be a translator; I want to learn a foreign language! And in my opinion, the way to do that is to not write anything in English at all while I’m studying. There’s a little lifehack for Duolingo — you can switch from learning Spanish for English speakers to learning English for Spanish speakers (this, in part, explains the large number of students in this course) so that the course will contain more English-to-Spanish assignments, although the amount of Spanish-to-English translations will still be very large. Whereas I want 100 % of the lesson time to be written in Spanish!

Second, I’m an adult, and I don’t need the studying process to be gamified at all. All those little people cheerfully winking, encouraging and advising me is one giant, irrelevant and annoying pain. There are even browser extensions that try to cut out all of these unnecessary functions, reducing the website’s visuals to the necessary level of minimalism.

Third, I’m an adult (yes, I’m repeating myself) and sometimes I don’t have the time for a full-sized lesson. While Duolingo has fairly short ones, the breakdown of the learning process into set lessons containing an XX amount of questions is primarily convenient for the learning platform, not the learner. I want to be able to repeat not twenty phrases, but, say, five or three, or even one. I want to be able to interrupt the studying process at any moment without losing progress! After all, I sometimes am only able to practice on rare breaks of undetermined duration between my main activities over tea and cookies, or during breaks between spending time with the kids. If I have only a literal spare minute, I want to do a couple of sets and maintain my progress.

Fourth, I want to be able to add new phrases at any stage of my study! After hearing or reading something new, useful or just interesting, I want to add the phrase to the list, letting the app ensure that this phrase will remain in my memory forever.

Fifth, but also no less important consideration — I want the program to indicate the wrong parts of the translation. Sometimes the entered text contains small mistakes or typos, catching which is difficult with a naked eye. I want the program to show the difference between my translation and the correct version, so that I can focus on learning Spanish, and not on the game of finding the wrong letter in a long phrase in a foreign language.

This is my wish list — I want Duolingo, but only with English-to-Spanish tasks, without gamification, saving progress after each task, with the ability to add new phrases and with the visualization of the errors made, even minor ones.

I think that’s where the preface can end and we can get to the heart of the matter. If you simply want to start learning Spanish, go to the next section, ‘Usage.’ If you want to see the app’s inner workings, go to the ‘How It Works’ section (near the end of the article).

Usage

Using Flywheel is extremely simple. At the start, you have just one file, phrases.txt (the file that comes with the application contains about two thousand phrases). Inside are many pairs of phrases, separated with a double vertical line, e.g.:

I love you || Te quiero

If the English phrase can be correctly translated into several different Spanish phrases, a single vertical line is used to separate them:

I know || Lo se | Ya se | Yo sé

If there are two English phrases that can also have multiple equivalent translations, a single vertical line is also used to separate them.

Of course, you can and should add your own phrase pairs to phrases.txt. This is the essence of Flywheel — you don’t have to memorize the dictionary, it’s just a template. Adjust the content of the lessons to suit your level of proficiency; move the phrase pairs you find most useful higher up in the dictionary; add pairs related to your job. Needless to say, the shell doesn’t care what language you’re learning. If you wish to learn French, bien accueillir! Want to learn Aleutian? No problem. Need to learn Aleutian as a native French speaker? Easy as pie!

Please don’t add single words to the dictionary! Sure, technically it’s possible, but it’s not particularly worthwhile from the perspective of language learning efficiency. Try adding phrases specifically, and if you want to add a specific new word to your vernacular it’s better to pick up a phrase which uses it in a specific context. This way you’ll not only remember the word better, but you’ll more easily move it from the passive phase to the active phase, as you won’t simply recognize it in a text or in speech, but will actually start applying it in writing and in speaking.

Next, simply run flywheel.py. Two more files will be added to your application folder — repetitions.json (this will record your progress and memorization of all completed phrase pairs) and user_statistics.txt (this will record the total number of exercises you have completed and will generate a general list of words you have managed to learn).

How It Works

If you are a beginner Python developer and want to try your hand at something simple but not useless, give Flywheel a whirl. Maybe you’ll be able to add some hot new features to it, and improve your Spanish while debugging it as well. Naturally, most of the methods used in the application don’t need a lot of describing, so I’ll focus only on the general approach and the key functions that are directly related to the analysis of user progress.

Recently I have been practicing the following method: I write a template main as if all of the application’s methods have already been developed and I just need to call them. This gives you sort of a bird’s-eye view of the code (even if it’s more like a penguin’s rather than an eagle’s :) and a rough estimate of the level of effort required. This is what I ended up with:

phrases_file_name = "phrases.txt"
repetitions_file_name = "repetitions.json"

if __name__ == "__main__":
    phrases_file_path = find_or_create_file(phrases_file_name)
    repetitions_file_path = find_or_create_file(repetitions_file_name)

    phrases = read_phrases(phrases_file_path)
    repetitions = read_repetitions(repetitions_file_path)
    can_work, error_message = data_assessment(phrases, repetitions)

    if can_work:
        message = merge(repetitions, phrases)
        print(message)
        while True:
            current_phrase = determine_current_phrase(repetitions)
            user_result = user_session(current_phrase)
            update_repetitions(repetitions, current_phrase, user_result)
            save_repetitions(repetitions_file_path, repetitions)
    else:
        print(error_message)
        exit()

The operating logic is roughly thus:
• we look for phrases.txt in the project directories (lots of phrase pairs separated by a dual vertical line, see the ‘Usage’ section for details); if we can’t find it, we create a blank file for future editing by the user;
• similarly, we look for repetitions.json (progress records and memorization degrees of all complete phrase pairs); if not found, we create an empty file;
• we create data structures from the information taken from phrases.txt and repetitions.json, and then evaluate whether we can work with given combination. If phrases.txt is not empty, then okay, we can convert phrase pairs to our internal format and transfer that information to repetitions.json. If repetitions.json is not empty, then also okay, we can work with the information we’ve already accumulated. Both phrases.txt and repetitions.json being empty is not okay, we have nowhere to draw the information we need to work, so we complain about this fact to the user, let them create phrases.txt with at least some minimal content;
• during the loop, we feed a new task to the user, picking the most relevant phrase we need at the moment from the phrase dictionary. If there are phrases that require repetition, we pick them first; if all completed tasks don’t require a refresher right now, we star