You are here

Communication between dictionaries and flashcard applications

We need a protocol for communication between dictionaries and flashcard applications.

Dictionary: App to translate for instance Japanese to Italian
Flashcard app: App to memorize words lists, useful for language students.

Here are a few way a dictionary and a flashcard app can cooperate:

use case 1)
User looks up a word in the dictionary, and wants to add this word as a new flashcard to the flashcards app.

use case 2)
User sees an unknown words on a flashcard, and wants to look it up on the dictionary

use case 3)
the dictionary might offer to learn a set of words using the flashcard app, for instance bookmarked searches (like Aedict's "notepad")

Please contribute other use cases, the sooner the better!

In the interest of all dictionaries and flashcard apps, let's create an open protocol that is usable by all targeted applications. The involvement of all is greatly appreciated.

Some work has begin on AnkiDroid-Aedict, but no concrete results yet:
http://code.google.com/p/ankidroid/issues/list?q=label:aedict

Thanks everyone!
Nicolas Raoul

Personally, as a dictionary app dev (Hanping Chinese-English Pro), I'm more immediately interested in use case 1 (and use case 2, later).

For use case 1, most of the work should be done on the flashcard app side: i.e. deciding which flashcard lists to update and how to arrange the dictionary entry data).

In my dictionary app, the user maintains multiple word/entry lists. The user adds dictionary entries (one-by-one) to one of any number of word lists (each with their own unique name). Think of it like a favourite system where the user can "star" an entry he is interested in. Only one word list is "active" at any one time - and this is the word list that is modified when the user "stars" an entry.

Every time the user "stars" an entry, the dictionary app can fire off the appropriate broadcast Intent (which can then be received by registered broadcast receivers (flashcard apps).

The intent data could include:

* All the dictionary entry data (e.g. key1="開", key2="开", key3="kai1", value="to open/to start"). Also allow multiple entries to be specified in the same intent.
* Metadata describing the entry data (e.g. key1Meta="zh-hant", key2Meta="zh-hans" key3Meta="zh-Latn-pinyin" valueMeta="en")
* The name of the word list (optional) (e.g. name="faves"). The flashcard app could just ignore this altogether.
* Versioning info describing the Intent format version supported. Maybe a minVersion and targetVersion

My personal preference is for this communication to be done as transparently as possible. In other words, when the user "stars" an entry, then no "picker" or other dialog should be shown.

Alternatively this could just happen the first time, so the user can say "Ok, when I "star" an entry, I want this flashcard app to do something". When a new flashcard app is installed, maybe this process needs to be repeated.

Hi I am the author of AnyMemo
AnyMemo will only use this information:
1. Question
2. Answer
3. Category (Optional)
4. Additional notes (Highly optional)

The follow meta data is useful
1. Question language
2. Answer language

I hope to implement one in the future release of AnyMemo.
When user want to add a card, he need to select one database in AnyMemo to add. AnyMemo will provide a list of recent-opened databases.
Hopefully, I can add an option to create a new database if user want. Of course this is the second step.

Would you please do some copy/paste work into http://anymemo.org/bugzilla
So I will work on it in the next release (Maybe 5.3.0).
Thank you very much!

What are people's thoughts on which apps should be responsible for what?

The approach I outlined above would mean the dictionary would broadcast a dictionary-specific (nothing about flashcards would be assumed) intent. So, the flashcard app would need to specifically listen/receive dictionary-specific intents and act accordingly.

Alternatively, the dictionary would broadcast a flashcard-specific intent and so flashcards would only need to listen/receive these intents.

Each approach has its own advantages. The first, makes it easy for non-flashcard apps to take advantage of these dictionary broadcasts. The second, makes it easy for non-dictionary apps to take advantage of flashcard broadcast receivers.

I don't think this is just a matter of wording. Its more a matter of whether the data model of the intent is closer aligned to that of a generic dictionary entry or that of a generic flashcard.

Could a flashcard dev outline the data format of the most generic flashcard?

It is possible to use JSON to pass string to the Intent. It can pass several cards together to the Receiver.

Hi,

I'm the developer of Flashcards ToGo (http://groups.google.de/group/flashcards-togo) and I also had the idea to standardize the protocol between a flashcard and a dictionary app. I think both dictionary and flashcard apps would benefit a lot from such a standardized protocol (if it is sufficient for most use cases).

This is my proposal for usecase 1, with some details still undecided => please comment and correct/refine it:

Use case 1
I would describe the use case as "create a new flashcard (eg. from a dictionary app)", and I would see this API as a flashcard-app centric api that other apps (typically dictionary apps) might call.

Intent calling direction: dictionary app => flashcard app

Responsibilities:
dictionary app:
- optionally let the user select text (eg. let the user choose one/many/all of the definitions of a word, and/or let user decide whether to include examples (if there are examples included in the definitions))
- should provide the language codes for the definitions

flashcard app:
- creating a new flashcard and assigning it to a deck of cards (if flashcard app supports more than one deck)
- creating two sides for the flashcard and automatically (or with the help of the user) assign the source/target texts to the correct sides
- do flashcard-app-specific preprocessing on the texts if required, eg. cutting off if too long, change encoding, ...
- creating the flashcard could be implemented as an interactive action (if user needs to be asked something, eg. choose a deck, or maybe user gets the newly created card displayed and has to go back to dictionary app) or as a non-interactive action (after creating the card, the intent will finish automatically) => I would tend to not standardize this and leave this to the implementation within the flashcard app

Action:
org.openintents.action.CREATE_FLASHCARD
Input arguments:
- org.openintents.extra.SOURCE_LANGUAGE: String, language code (todo: which standard? ISO 639-1 or ISO 639-2?) of the first side
- org.openintents.extra.TARGET_LANGUAGE: as above, but for second side
- org.openintents.extra.SOURCE_TEXT: text of the first side (todo: encoding? UTF-16?)
- org.openintents.extra.TARGET_TEXT: as above, but for second side (must not repeat the word from the SOURCE_TEXT side)

Output:
- nothing (dictionary app probably is not interested in whether creating the flashcard was successful or not)

Open questions:
1. Is a source and target side sufficient, or do we need a more generic approach which allows 3 or more sides of a card? (I'm not learning japanese or chinese => can someone with experience with these languages maybe respond?)
2. Agree on encoding and language code
3. Do we need any CATEGORY or other argument? I tend to say no, as a dictionary app generally will not be able to provide this information as required by a flashcard app
4. Do we need a version info (as suggested above) for the protocol api? I tend to say no for the initial protocol, hoping that further extensions to the protocol can be made in a backward-compatible way...

Notes:
1. I call the two sides "source" and "target", other refer to it as front/back side, question/answer, ...

This is a proposal from my point of view, but I am open to any modifications. I would be really happy if we manage to agree on a protocol and spread the word about it... Of course I would implement it in the next version of Flashcards ToGo! If we can agree on an API for usecase 1, usecase 2 should be easy to standardize, too...

Any constructive comments welcome!

Oliver

Hi glad to see you! I am the author of AnyMemo. I suggest the main API can be like that. The broadcast receiver will pop up some dialog for user to fill other info like category. The locale should be optional since some flashcard software does not use it at all. AnyMemo uses locale a lot. So if the locale info is ignored, AnyMemo will allow user to select the locale.

liberty, when you say "locale should be optional", are you talking about SOURCE_LANGUAGE and TARGET_LANGUAGE?
As the source application is a dictionary, we can reasonably assume that it has both.
I support requiring both.
Sometimes it can be the same language, for instance a French-French dictionary or a legal lexicon.
If you can think of any dictionary that does not have a source language and a target language, please let us know as soon as possible.

If that's a language dictionary, it is true. But If it is a mathematical formula for chemical formula dictionary, it may not be true. Also many stardict dictionary does not have such info in the dictionary.

Welcome to the discussion, onoelle!

I would argue for a dictionary-centric api. Why? Because a dictionary app is lower level than a flashcard app and, in general, you want higher level things to know about lower level things and not the other way around.

Thoughts?

I think dictionaries and flashcard apps are at the same level. To implement all use cases, both will need to know about each other.
A dictionary implementing use case 1 knows what a flashcard is, because its UI has a button such as "Create a flashcard", right?
The intent of use case 1 is really to create a new flashcard, so I think the intent should not be abstracted from the concept of flashcard.

I would definitely say a dictionary app is at the lower level.

The interaction between dictionary and flashcard doesn't make the dictionary experience any richer. It makes it more useful but that's slightly different. However, the flashcard app experience is definitely better if it can pop up dictionary definitions etc.

I don't see it as a "Create flashcard" button. More specifically it would be something which says "This is a word that is important to me". I show that as a "star" icon. So another broadcast receiver might want to do something like back it up to an online location. Another dictionary app might receive the intent and say, "Hey, I also have that word, but this time with a Russian description!". Another receiver might want to show the user sample sentences etc.

So its not just flashcard apps that would benefit from this.

I really do think its lower level. Its very unlikely that a user will have a flashcard app but no dictionary app. However, the other way around would be much more common. When you start learning a language, a dictionary is the first thing you buy. Its the base of all other study material.

Thanks for your input from a dictionary developer point of view, Mark.

However, I do agree with Nicolas in that for usecase 1 the dictionary app needs to know what a flashcard is and should offer a button to create one from an entry. This can be a selling point for the dictionary app that it supports this usecase (and at the same time for the flashcard app, too).
I would implement this as a normal intent (no broadcast), where the user can initially choose which flashcard app (if she has installed more than one that supports this usecase) should handle the intent (and make this the default, if she wants).

Just fire out a broadcast intent when you "star" an entry is too generic, I think. Looking up example sentences, back the word up to an online location and creating a flashcard are quite different things, the user might want to perform one action on one defintion and another on another definition, so this should not be mixed up in a generic thing.
=> let's create a protocol for creating a flashcard, not something so generic that we have difficulty to give the intent a name.

For usecase 2, I would expect the dictionary app to offer a generic api to lookup a word (without anything flashcard-specific) and return its definition (if found). The flashcard app would be the client of that api, but any other app should be able to use it, too.

Oliver

I don't think such protocol should be complex. Oliver's suggestion is very good. The protocol should just transfer Q / A for flash cards and the words that need to look up for dictionaries. That's enough for most of the cases. The flash card apps can handle the additional info after receiving the intent and the dictionary app as well. Maybe the flashcard app can popup a dialog to input app specific info.

To get the remaining open points narrowed down, I propose the following next steps:

- create a pseudo-flashcard app and a pseudo-dictionary app (just dummy applications consisting of a few lines of code to demonstrate how to call or receive an intent) to exemplify how the use cases must be implemented on both sides/what the arguments are. I think a few lines of code can describe the options (eg. whether language code is mandatory or optional) and remaining open issues (language code, UTF-8 vs. UTF-16) best.
- I will ask the people from openintents.org, whether the interested developers from this discussion could get write access to the svn hosted on http://code.google.com/p/openintents to create and modify these two dummy applications in that repository (alternatively, we could create a completely new project at google code).
- I think we should maintain a list of apps that are candidates for supporting our use cases and spread the word about this standard, and keep track of which app developers have already been notified of this standard, and naturally which apps support one or more of these usecases
- app developers who want to extend/modify the api, must file an issue for the extension or modification and that issue should be discussed by some of us before any modification to the standard protocol will be done

Is that a suitable roadmap to reach our goal? (I will ask for repository access in any case)

Comments welcome

Who would be interested to actively contribute to the standard and maybe write a few lines of code or documentation illustrating a certain aspect?
Oliver Nölle (Flashcards ToGo)

Nice! I had not thought about this, and it is indeed a really good idea!!
Creating sample code will allow:
- Brainstorming on code independently from any particular application.
- Easy integration by application owners.

The code's license should be Public Domain, so that proprietary apps can reuse it too.

Google Code requires people to be authorized before they can contribute code :-( For hassle-free development, I would recommend GitHub, it allows everybody to contribute without having to ask for permission (in their branch, visible to everyone for review and merge), and it encourages experiments. See for instance http://github.com/nicolas-raoul/Anki-Android/network

For the applications list, I guess a wiki would be the best tool. Github's wiki is quite special and Google Code's wiki is not really editable by everyone, so a Wikia.com wiki could do the trick. If OpenIntents.org had a wiki, that would be the best, but I haven't seen one.

We have many flash card developers, are there any more diction developers to discuss this?

I first talked about this with Martin Vysny, the developer of Aedict.
I told him about this discussion.
Not sure about others. Do you know where dictionary developers hang out?

The author of a Chinese-English dictionary named Hanping has contacted me. But there is no further discussion though. I personally like Colordict. I hope to get him involved.

Hi, I'm the author of StudyDroid.

I'm totally in favor of dictionary/flashcard communication protocol. It wouldn't necessarily have to be just dictionaries either. Any kind of app that wants to facilitate learning could implement it.

I'm a little iffy on how the user would interact with the flashcard app in use case 2 (a touch, maybe a long press? I don't know), but that's more a problem for the developers to figure out than the protocol.

I also like the 'Star' broadcast idea. Less clicks is usually better. The only problem is that it's ambiguous for flashcard applications that group your cards into distinct sets, which set the 'starred' information should be inserted into. If you're studying multiple languages or disciplines, it could get messy.

Hello all,

I started implementing a sample app (actually two: dic app and flashcard app) based on Oliver's protocol.
Very small code, that everyone will be able to discuss and copy-paste into their apps.

Before uploading the source code: What namespace should I use?
I asked OpenIntents.org whether we can use "org.openintents..sample"

What should be?
Your suggestions are welcome!

It would be cool if it suggests "intent" "dictionary" "flashcard", but it is not required. Here are my friends' suggestions:
Ramzi: dicflash indicflash
Mose: ibedif idaf dic2card
Krush: intendo intendi indiction intiflash
Edu Zamora: difain
Daniel: indiflash

I quite like "indiflash" and "difain", and they are not used already (few Google hits).

What do you think?

Nicolas Raoul

I suggest wildgoose cardpigeon dicdove

Interesting names, I am not sure to get it, can you elaborate on the idea of "pigeon" for instance?

A few days ago I asked whether the code samples could use the org.openintents namespace, and I got a reply quite fast :-)
Here it is:

> Hi Nicolas,
>
> Thanks for pushing the flashcard project:
> http://www.openintents.org/en/node/720
>
> You can get more visibility from the core OpenIntents developers team
> if you move the discussion to our developer's group:
> http://groups.google.com/group/openintents
>
> As for the namespace, we tend to use rather basic words (like
> "flashlight", "shopping", "filemanager", etc.), so something like
> "flashcards" would be more appropriate than "indifla". The official
> application name can then still be different, but we can postpone this
> discussion to a later stage.
>
> Please send your first version as a patch or zip file, we'll review
> and upload it, and if everything is fine, we'll grant you commit
> rights.
>
> The directory structure could be
> trunk/Flashcards
> trunk/Dictionary
> trunk/samples/FlashcardSample
> trunk/samples/DictionarySample
> or similar.
> Alternatively, all could be added to a separate directory:
>
> trunk/flashcards/Flashcards
> trunk/flashcards/Dictionary
> trunk/flashcards/samples/FlashcardSample
> trunk/flashcards/samples/DictionarySample
> (see e.g. trunk/sensorsimulator)
> (directories start with lower letter, projects with capital letter).
>
> Peli
> www.openintents.org
>
> On Thu, Sep 2, 2010 at 6:41 AM, wrote:
>> Nicolas Raoul sent a message using the contact form at
>> http://www.openintents.org/en/contact.
>>
>> Hello!
>> I am writing code samples for the new intents we are designing (between
>> dictionaries and flashcard apps).
>> Which namespace should the samples use?
>> Can I use "org.openintents.indifla.sample" ?
>> Thanks!
>> Nicolas Raoul

What do you all think?
It seems that there is a certain degree of confusion, we are not producing any application, just a protocol and associated sample code.
I thought OpenIntents.org was a place to collaboratively design and maintain intents, but I might have been mistaken. If so, maybe anyone knows a better place to carry on? Maybe back to our starting point: http://www.droidforums.net/forum/droid-applications/5536-review-flashcar...

Peli has a point that simpler names are best, but in our case the idea can't be resumed in a single word... maybe IntentsBetweenDictionariesAndFlashcardsApps ? A bit long... oh, by the way, what do you think about "Indiclash" (in dic lash for INtent DICtionary fLASHcard, "indi" for independance and openness, "clash" to express interaction and hotness) ?

I have two sample apps coded for use case 1, just waiting for a good project name before I upload them so that you can all improve it/comment on it/propose new ideas.

Cheers!
Nicolas Raoul

Hi Nicolas,

thanks for taking the initiative, I was just about to start something on google code, but I was simply too busy to get started.

Regarding the namespace:
I also thought about something like fladict, or maybe fladictand (FLAshcard DICTionary protocol for ANDroid), google gives 0 hits on "fladictand", there might be a fladictios (the equivalent for Apple's iOS, if this integration is technically possible on that platform).

However, I think that this name should be just a common headline for two intents:
Use case 1 (and use case 3 also, I think) is an intent that flashcard apps offer. Nothing dictionary-specific here, it just happens that dictionaries might be the number one apps who would call that intent.
Use case 2 is an intent that dictionaries offer. Again, nothing flashcard-specific here, it just happens that from flashcard apps it makes sense to call that intent.
A dictionary or flashcard app can of course decide to only implement/support one of these use cases.

So maybe we can go for something like
org.openintents.flashcard.sample
- sample app that shows how to receive the intent from use case 1
- at the same time, the sample app could show how to call the intent from use case 2
org.openintents.dictionary.sample
- sample app that shows how to receive the intent from use case 2
- at the same time, the sample app could show how to call the intent from use case 1

and maybe using that directory layout:
> trunk/flashcards/samples/FlashcardSample
> trunk/flashcards/samples/DictionarySample

And if we talk about both (or all three intents, at the moment I would focus on the first two), we call it "indiflash" or "fladictand" or ...

I wouldn't discuss too much about the directory layout, because I'm more curious to look and comment on the code, and hopefully we can agree soon and build it all into our apps... And at the end I hope we have a agreed-upon protocol, described on openintens.org and with links to some sample code (whatever directory)...

Oliver

Indeed, use case could be separated into flashcard-aware intents and dictionary-aware intents. Those sets are probably independent, potentially leading to two sub-projects. That means 4 sample applications. Feel free to contribute these changes to Github :-)

I just committed the code for use case 1.
The code is on Github.com which means that anyone can fork and modify the code, and everyone can see the work of everyone, and merge from the forks they like. I will merge from all forks, based on consensus, Wikipedia-style.

http://github.com/nicolas-raoul/Indiclash

For those not familiar with Git, "fork" is just a kind of branch where you can do whatever you want. Here is how to fork:
http://help.github.com/forking
Git can be a bit overwhelming at first, but keep trying, it is rewarding afterwards.
If you have any question, please ask :-)
If someone is really allergic to Git, good old patches are welcome too.

Once you have your local repo, open Eclipse, "File→Import→Existing Projects Into Workspace", find the two projects where your repo is, accept and enjoy!

When people start pushing their own changes, we will be able to see branches that need merges here:
http://github.com/nicolas-raoul/Indiclash/network

If you don't have time for Eclipse right now, you might want to test the dictionary and flashcard apps by installing them from the Android Market (Indiclash *). Install both app, open the dictionary, click the button, and the flashcard app should show the fields that have been sent through the Intent.

The code for use case 1 should be working, I just tested it. It is very minimalist.
The project name and namespace can be changed when better ones are found.
Please try the code, improve it, implement the two other use cases, spot all problems, and discuss them!

onoelle created his branch in Github and contributed the implementation of use case 2.
Thanks to the magic of Git, in two clicks I merged his contributions into my master.
Thanks a lot onoelle!

Everybody, please check the source and improve it if possible :-)
Do you see any issue revealed by the code?

By reading onoelle's code, a small question arises about use case 2 (flashcard app launches a dictionary search).

My idea was that the user would see a strange word on a flashcard, click "Look up this word", and that would launch the user interface of a dictionary app.
So I would not have used "startActivityForResult" but just "startActivity". The user browses the various definitions available in the dictionary, maybe search similar words, and then, after he understood, he comes back to the flashcard app to review the rest of the cards.

In onoelle's implementation, a translation is retrieved from the dictionary app, but without showing it, and the translation is shown to the user within the flashcard app's user interface.

What do you all think?

Good point, Nicolas.

As there will be an exact match only in rare cases, I think we should expect some sort of UI from the dictionary to come up after the Intent was called, maybe to narrow down the search, pick one of many matching entries, or refine the search...

I would still like to see the possibility to return text to the calling app (without manually copying it first to the clipboard, which would be another possibility). The user could either just press the return button (no result returned), or somehow "select/click" an entry to return its text to the calling app.
(I'm doing something similar with the Google Translate integration in my Flashcards ToGo app)

=> so if it does not make things much more complicated, I would like to enable returning data to the caller, even if a dictionary app might decide to not support returning any data to the sender.

=> so the code for usecase 2 needs to be modified to simulate some kind of UI of the dictionary app coming up. As soon as I have time, I try to provide a patch (GitHub really handles this case very well - a pleasant experience and a good choice by you, Nicolas!)

More comments, thoughts on that?
Any dictionary developer?

Oliver

Great to see some discussion and work coming along in this area!

Disclaimer: I haven't had time to look in depth at the work that has been done so far, so apologies if my thoughts overlap what has already been said or if they are in a different direction to the existing work.

As a dictionary dev, this is really quite a complex area. Some things to consider:

1. There may be multiple dictionary apps installed on a user's device (this is obvious, but wanted to write this for completeness)

2. A dictionary app may have multiple dictionaries spanning either one or multiple language pairs. Here are some app types:
a) One "From" language, one "To" language, one data source. e.g. Collins French-English only
b) One "From" language, one "To" language, multiple data sources. e.g. Collins French-English & Oxford French-English in one app
c) One "From" language, multiple "To" languages. e.g. Collins French-English & Collins French-German in one app
d) Multiple "From" languages. i.e. Generic dictionary apps like ColorDict

3. A user may use multiple dictionaries for a single language-pair spanning multiple apps. For example, a user may use a Chinese-English dictionary in dictionary app A, and also a different Chinese-English dictionary in dictionary app B.

What does this mean?

Well, when a flashcard app wants to bring up a dictionary search result, which app should be called? Does the flashcard app know the language of the word already, or does it want the dictionary app to figure that out?

A dictionary app can express its language support using some kind of Intent Filter or metadata tag. I would suggest a dictionary app that focuses on one language (e.g. Chinese-to-X) explicitly expresses this in its Manifest, whereas something like ColorDict would express a more generic intent filter/metadata tag.

If the flashcard app already knows the language then it may want to only show the list of dictionary apps that support that language. So it would show all the dictionary apps that explicitly support that language and then would query the generic dictionary apps (maybe using a ContentProvider) for their language support.

The first time the flashcard user wants to bring up a dictionary search, they can select the dictionary app (and maybe dictionary within the dictionary app) and specify to remember that choice in future.

Finally, if you want to retrieve dictionary data from dictionary apps, then consider ContentProviders. You can define/specify a URL the includes the word you want to lookup (maybe including wildcards) and optional params that can include any of "from" language, "to" language preference, dictionary preference. One advantage of using ContentProviders is that you can collect results from different dictionary apps and always present the results in a consistent style (either consistent across all apps, or consistent with your flashcard app).