Super Parrot Documentation

Creating a dictionary

A dictionary is written in a spreadsheet: a few CSV files arranged in folders, plus course notes in Markdown. You import them as they are, or bundled into a .parrot file to share.

The complete example

This page follows a small, real dictionary, “At the café”: French for English speakers, with 10 meanings, two exercise series and one lesson. It imports as is into the app; download it to try it or to start from it.

Two ways to create

How the files are organised

at-the-cafe/
├── dictionary.csv            the dictionary: title, author, version (a single .csv at the root)
├── categories/               grammar: noun, verb, masculine, level A1…
├── tags/                     topics: At the café, Drinks…
├── abbreviations/            abbreviations shown: n (m), n (f), v…
├── patterns/                 unmarked affixes: a, to, un, une
├── vocabulary/               meanings and their words in each language
├── exercises/                exercise series
├── lessons/                  the course outline: chapters and lessons
└── resources/course/…        course notes in Markdown

Each folder can hold as many files as you like (one per topic, one per chapter…). A missing folder simply means “no data of this type”. To import, zip the folder, or choose the folder itself in the import sheet.

Spreadsheet rules. UTF-8 encoding; ; as separator (a table copied from a spreadsheet, separated by tabs, is accepted too); first line = column names. Empty lines and lines starting with # are ignored: use them for comments. An x cell means “yes”.

1. The dictionary

A file of attributes: one line per piece of information, one line per language for the title. An empty attribute cell repeats the previous line's. WORKBOOK means a dictionary with a course.

en/at-the-cafe/dictionary.csv — download

In a spreadsheet
ABC
1attributelocalevalue
2referenceat-the-cafe
3titleenAt the café
4frAu café
5authorYour name
6typeWORKBOOK
7version1.0
The same file as text: one line per row, cells separated by ";" (same colour = same column)
attribute;locale;value
reference;;at-the-cafe
title;en;At the café
;fr;Au café
author;;Your name
type;;WORKBOOK
version;;1.0
The columns
A attributerequiredName of the information: reference, title, author, type, version… Empty = same as the line above. The export adds id: the internal identifier, which finds the object again on reimport; not to be written by hand.
B localerequiredLanguage of the value, for what is translated (the title). Empty otherwise.
C valuerequiredThe value.

2. Categories and tags

Two trees: categories for grammar (part of speech, gender, level…) and tags for topics. Each node takes one line per language; parent places it under another node; selectable (x) makes it assignable to a word and usable in a filter.

Prefer the shared references (noun, verb, mas, fem, niv-a1…): that is how two dictionaries recognise the same category.

en/at-the-cafe/categories/categories.csv — download

In a spreadsheet
ABCDEFG
1referenceparentlocalecategoryselectableoptionaldescription
2# Grammar: the references (noun, verb, mas…) are those of Super Parrot's common list.
3grammarengrammar
4frgrammaire
5posgrammarenpart of speech
6frnature du mot
7nounposennounx
8frnom
9verbposenverbx
10frverbe
11locutionposenphrasex
12frlocution
13genregrammarengender
14frgenre
15masgenreenmasculinexx
16frmasculin
17femgenreenfemininexx
18frféminin
19# CEFR level: the "niveau" branch, filled by the level column of the vocabulary.
20niveauenlevel
21frniveau de maîtrise
22niv-a1niveauenA1xx
23niv-a2niveauenA2xx
The same file as text: one line per row, cells separated by ";" (same colour = same column)
reference;parent;locale;category;selectable;optional;description
# Grammar: the references (noun, verb, mas…) are those of Super Parrot's common list.
grammar;;en;grammar;;;
;;fr;grammaire;;;
pos;grammar;en;part of speech;;;
;;fr;nature du mot;;;
noun;pos;en;noun;x;;
;;fr;nom;;;
verb;pos;en;verb;x;;
;;fr;verbe;;;
locution;pos;en;phrase;x;;
;;fr;locution;;;
genre;grammar;en;gender;;;
;;fr;genre;;;
mas;genre;en;masculine;x;x;
;;fr;masculin;;;
fem;genre;en;feminine;x;x;
;;fr;féminin;;;
# CEFR level: the "niveau" branch, filled by the level column of the vocabulary.
niveau;;en;level;;;
;;fr;niveau de maîtrise;;;
niv-a1;niveau;en;A1;x;x;
niv-a2;niveau;en;A2;x;x;
The columns
A referenceReference of the node (noun, drinks). Optional but recommended: the other files cite it. Empty on translation lines.
B parentParent node, by its reference. Empty = at the root. On the opening line only.
C localerequiredLanguage of the line's label (en, fr).
D categoryrequiredLabel of the category in that language (noun, masculine).
E selectablex = can be set on a word and chosen in a filter. Empty = mere grouping.
F optionalx = marked optional in the list of categories.
G descriptionFree note, not translated, kept in the dictionary and given back by the export.
H idInternal identifier (UUID), written by the export. On reimport it finds the object unambiguously, before the reference; if unknown, it is kept for the created object. Not to be filled in by hand, nor cited elsewhere: the other columns name objects by their reference.

en/at-the-cafe/tags/themes.csv — download

In a spreadsheet
ABCDEFG
1referenceparentlocaletagselectableoptionaldescription
2theme-cafeenAt the caféx
3frAu café
4drinkstheme-cafeenDrinksx
5frBoissons
The same file as text: one line per row, cells separated by ";" (same colour = same column)
reference;parent;locale;tag;selectable;optional;description
theme-cafe;;en;At the café;x;;
;;fr;Au café;;;
drinks;theme-cafe;en;Drinks;x;;
;;fr;Boissons;;;
The columns
A referenceReference of the node (noun, drinks). Optional but recommended: the other files cite it. Empty on translation lines.
B parentParent node, by its reference. Empty = at the root. On the opening line only.
C localerequiredLanguage of the line's label (en, fr).
D tagrequiredLabel of the tag (the theme) in that language.
E selectablex = can be set on a word and chosen in a filter. Empty = mere grouping.
F optionalx = marked optional in the list of categories.
G descriptionFree note, not translated, kept in the dictionary and given back by the export.
H idInternal identifier (UUID), written by the export. On reimport it finds the object unambiguously, before the reference; if unknown, it is kept for the created object. Not to be filled in by hand, nor cited elsewhere: the other columns name objects by their reference.

3. Abbreviations and affixes

An abbreviation sums up a word's grammar as a paper dictionary does (café n (m)). A word gets the one whose categories are all its own, the most complete first.

A pattern adds a prefix or suffix around the word, shown in grey and never marked: the article, the to of the English infinitive. Spaces count (une , to ).

en/at-the-cafe/abbreviations/abbreviations.csv — download

In a spreadsheet
ABCD
1referencelocaleabbreviationcategories
2nmenn (m)noun, mas
3frnm
4nfenn (f)noun, fem
5frnf
6nennnoun
7frn
8venvverb
9frv
10phrenphrlocution
11frloc
The same file as text: one line per row, cells separated by ";" (same colour = same column)
reference;locale;abbreviation;categories
nm;en;n (m);noun, mas
;fr;nm;
nf;en;n (f);noun, fem
;fr;nf;
n;en;n;noun
;fr;n;
v;en;v;verb
;fr;v;
phr;en;phr;locution
;fr;loc;
The columns
A referenceOptional: by default, the abbreviation of the opening line.
B localerequiredLanguage of the abbreviation: each learner reads it in their own.
C abbreviationrequiredThe abbreviation in that language (n, nm).
D categoriesThe categories it sums up, by reference, separated by commas. On the opening line only.
E idInternal identifier (UUID), written by the export. On reimport it finds the object unambiguously, before the reference; if unknown, it is kept for the created object. Not to be filled in by hand, nor cited elsewhere: the other columns name objects by their reference.

en/at-the-cafe/patterns/patterns.csv — download

In a spreadsheet
ABCDE
1referencelocalenameprefixsuffix
2art-unenFrench masculine noun with indefinite article
3fr-FRun
4art-uneenFrench feminine noun with indefinite article
5fr-FRune
6art-aenEnglish noun with indefinite articlea
7verb-infenEnglish infinitiveto
The same file as text: one line per row, cells separated by ";" (same colour = same column)
reference;locale;name;prefix;suffix
art-un;en;French masculine noun with indefinite article;;
;fr-FR;;un ;
art-une;en;French feminine noun with indefinite article;;
;fr-FR;;une ;
art-a;en;English noun with indefinite article;a ;
verb-inf;en;English infinitive;to ;
The columns
A referenceReference of the pattern, which words cite in their pattern column. Optional, but a short reference (art-a) is handier.
B localerequiredLanguage of the line: that of the name, or that of the words that get the affix (fr-FR).
C namerequiredName of the pattern in that language. May stay empty on a line that only carries an affix.
D prefixShown before the word, never marked (the article). Spaces count: a .
E suffixShown after the word, never marked. Spaces count:  qqch.
F idInternal identifier (UUID), written by the export. On reimport it finds the object unambiguously, before the reference; if unknown, it is kept for the created object. Not to be filled in by hand, nor cited elsewhere: the other columns name objects by their reference.

4. Vocabulary

A meaning line opens a meaning; the word lines that follow are its words, one per language (and several for synonyms). Words carry the language with its country (en-GB, fr-FR), categories, tags and pattern, given by their reference (noun, drinks, art-a): it depends neither on the language nor on a later change of wording. A label is accepted too, but becomes ambiguous as soon as two objects share it.

en/at-the-cafe/vocabulary/cafe.csv — download

In a spreadsheet
ABCDEFGHIJKLM
1typereferencelocaletextcontexttranslation_contextiparegisterfrequencylevelcategoriestagspattern
2# One meaning (meaning line) followed by its words, one per language. The text is the bare
3# word: the article and "to" come from the pattern and are not marked.
4meaningcoffee
5worden-GBcoffeeniv-a1noundrinksart-a
6wordfr-FRcaféboissonkafeniv-a1noun, masdrinksart-un
7meaningtea
8worden-GBteaniv-a1noundrinksart-a
9wordfr-FRthéniv-a1noun, masdrinksart-un
10meaningwater
11worden-GBwaterniv-a1noundrinks
12wordfr-FReauoniv-a1noun, femdrinks
13meaningcroissant
14worden-GBcroissantniv-a1nountheme-cafeart-a
15wordfr-FRcroissantkʁwasɑ̃niv-a1noun, mastheme-cafeart-un
16meaningsugar
17worden-GBsugarniv-a1nountheme-cafe
18wordfr-FRsucreniv-a1noun, mastheme-cafe
19meaningbill
20worden-GBbillat a restaurantniv-a1nountheme-cafeart-a
21wordfr-FRadditionniv-a1noun, femtheme-cafeart-une
22meaningwaiter
23worden-GBwaiterniv-a1nountheme-cafeart-a
24wordfr-FRserveurniv-a1noun, mastheme-cafeart-un
25meaningorder
26worden-GBorderat a caféniv-a2verbtheme-cafeverb-inf
27wordfr-FRcommanderniv-a2verbtheme-cafe
28meaningpay
29worden-GBpayniv-a1verbtheme-cafeverb-inf
30wordfr-FRpayerniv-a1verbtheme-cafe
31meaningthe-bill-please
32worden-GBThe bill, please.niv-a1locutiontheme-cafe
33wordfr-FRL'addition, s'il vous plaît.niv-a1locutiontheme-cafe
The same file as text: one line per row, cells separated by ";" (same colour = same column)
type;reference;locale;text;context;translation_context;ipa;register;frequency;level;categories;tags;pattern
# One meaning (meaning line) followed by its words, one per language. The text is the bare
# word: the article and "to" come from the pattern and are not marked.
meaning;coffee;;;;;;;;;;;
word;;en-GB;coffee;;;;;;niv-a1;noun;drinks;art-a
word;;fr-FR;café;boisson;;kafe;;;niv-a1;noun, mas;drinks;art-un
meaning;tea;;;;;;;;;;;
word;;en-GB;tea;;;;;;niv-a1;noun;drinks;art-a
word;;fr-FR;thé;;;;;;niv-a1;noun, mas;drinks;art-un
meaning;water;;;;;;;;;;;
word;;en-GB;water;;;;;;niv-a1;noun;drinks;
word;;fr-FR;eau;;;o;;;niv-a1;noun, fem;drinks;
meaning;croissant;;;;;;;;;;;
word;;en-GB;croissant;;;;;;niv-a1;noun;theme-cafe;art-a
word;;fr-FR;croissant;;;kʁwasɑ̃;;;niv-a1;noun, mas;theme-cafe;art-un
meaning;sugar;;;;;;;;;;;
word;;en-GB;sugar;;;;;;niv-a1;noun;theme-cafe;
word;;fr-FR;sucre;;;;;;niv-a1;noun, mas;theme-cafe;
meaning;bill;;;;;;;;;;;
word;;en-GB;bill;at a restaurant;;;;;niv-a1;noun;theme-cafe;art-a
word;;fr-FR;addition;;;;;;niv-a1;noun, fem;theme-cafe;art-une
meaning;waiter;;;;;;;;;;;
word;;en-GB;waiter;;;;;;niv-a1;noun;theme-cafe;art-a
word;;fr-FR;serveur;;;;;;niv-a1;noun, mas;theme-cafe;art-un
meaning;order;;;;;;;;;;;
word;;en-GB;order;at a café;;;;;niv-a2;verb;theme-cafe;verb-inf
word;;fr-FR;commander;;;;;;niv-a2;verb;theme-cafe;
meaning;pay;;;;;;;;;;;
word;;en-GB;pay;;;;;;niv-a1;verb;theme-cafe;verb-inf
word;;fr-FR;payer;;;;;;niv-a1;verb;theme-cafe;
meaning;the-bill-please;;;;;;;;;;;
word;;en-GB;The bill, please.;;;;;;niv-a1;locution;theme-cafe;
word;;fr-FR;L'addition, s'il vous plaît.;;;;;;niv-a1;locution;theme-cafe;
The columns
A typerequiredmeaning opens a meaning; each word that follows is one of its words.
B referenceOn meaning: reference of the meaning (coffee), to give to meanings the course cites. On word: optional.
C localerequiredLanguage of the word, with the country (en-GB, fr-FR). Empty on meaning.
D textrequiredThe bare word (coffee, not a coffee) or the sentence. Empty on meaning.
E contextSays which sense of the word is meant, in the word's language (at a restaurant).
F translation_contextContext shown to the learner being asked, in their language: en§vehicle.
G ipaPronunciation in IPA, when speech synthesis gets it wrong.
H registerRegister: a category of the registre branch.
I frequencyFrequency: a category of the frequence branch.
J levelCEFR level: a single category of the niveau branch (niv-a1).
K categoriesThe word's other categories (part of speech, gender…), by reference, separated by commas.
L tagsThe word's tags (its themes), by reference, separated by commas.
M patternThe word's pattern, by reference: its unmarked affixes.
N idInternal identifier (UUID), written by the export. On reimport it finds the object unambiguously, before the reference; if unknown, it is kept for the created object. Not to be filled in by hand, nor cited elsewhere: the other columns name objects by their reference.

5. Exercises

A series starts with its _ lines (title, instruction, language of question and answer), then each item by its number. Text follows the Parrot Markup syntax: {?1§} marks a gap, {?1§the answer} the filled gap, {type=affix§.} punctuation shown but never marked. One answer or proposal line per accepted answer, never several in one cell.

en/at-the-cafe/exercises/cafe.csv — download

In a spreadsheet
ABCDEFG
1topicitemattributesectionindexlocalevalue
2# Series 1: translate. The question is in English (section 1), the answer in French.
3cafe-translate_titleen-GBAt the café — translate
4fr-FRAu café — traduire
5wordingen-GBTranslate into French.
6question1en-GB
7answer1fr-FR
8categoriesniv-a1
9tagstheme-cafe
101question{?1§A coffee, please}{type=affix§.}
11answer{?1§Un café, s'il vous plaît}{type=affix§.}
122question{?1§I'd like a tea}{type=affix§.}
13answer{?1§Je voudrais un thé}{type=affix§.}
14{?1§J'aimerais un thé}{type=affix§.}
153question{?1§The bill, please}{type=affix§.}
16answer{?1§L'addition, s'il vous plaît}{type=affix§.}
17# Series 2: one gap to fill, with proposals (one per line).
18cafe-fill-in_titleen-GBAt the café — fill in
19fr-FRAu café — compléter
20wordingen-GBChoose the right word.
21question1fr-FR
22answer1fr-FR
23categoriesniv-a1
241questionJe {?1§} un café, s'il vous plaît.
25answer{?1§voudrais}
26proposal1voudrais
271veux
281prends
292questionL'{?1§}, s'il vous plaît !
30answer{?1§addition}
31proposal1addition
321note
331facture
343questionVous voulez du {?1§} dans votre thé ?
35answer{?1§sucre}
36proposal1sucre
371sel
381beurre
The same file as text: one line per row, cells separated by ";" (same colour = same column)
topic;item;attribute;section;index;locale;value
# Series 1: translate. The question is in English (section 1), the answer in French.
cafe-translate;_;title;;;en-GB;At the café — translate
;;;;;fr-FR;Au café — traduire
;;wording;;;en-GB;Translate into French.
;;question;1;;en-GB;
;;answer;1;;fr-FR;
;;categories;;;;niv-a1
;;tags;;;;theme-cafe
;1;question;;;;{?1§A coffee, please}{type=affix§.}
;;answer;;;;{?1§Un café, s'il vous plaît}{type=affix§.}
;2;question;;;;{?1§I'd like a tea}{type=affix§.}
;;answer;;;;{?1§Je voudrais un thé}{type=affix§.}
;;;;;;{?1§J'aimerais un thé}{type=affix§.}
;3;question;;;;{?1§The bill, please}{type=affix§.}
;;answer;;;;{?1§L'addition, s'il vous plaît}{type=affix§.}
# Series 2: one gap to fill, with proposals (one per line).
cafe-fill-in;_;title;;;en-GB;At the café — fill in
;;;;;fr-FR;Au café — compléter
;;wording;;;en-GB;Choose the right word.
;;question;1;;fr-FR;
;;answer;1;;fr-FR;
;;categories;;;;niv-a1
;1;question;;;;Je {?1§} un café, s'il vous plaît.
;;answer;;;;{?1§voudrais}
;;proposal;;1;;voudrais
;;;;1;;veux
;;;;1;;prends
;2;question;;;;L'{?1§}, s'il vous plaît !
;;answer;;;;{?1§addition}
;;proposal;;1;;addition
;;;;1;;note
;;;;1;;facture
;3;question;;;;Vous voulez du {?1§} dans votre thé ?
;;answer;;;;{?1§sucre}
;;proposal;;1;;sucre
;;;;1;;sel
;;;;1;;beurre
The columns
A topicReference of the series, on its first line (cafe-translate); the course cites it. Optional: by default, taken from the title.
B itemrequired_ = what applies to the whole series; otherwise the item's number, which groups its lines. Empty = same as the line above.
C attributerequiredWhat the line gives: title, wording (instruction), question, answer, proposal, categories, tags… Empty = same as the line above. The export adds id: the internal identifier, which finds the object again on reimport; not to be written by hand.
D sectionSection number (#1§). On the series: the section of the question and that of the answer.
E indexNumber of the gap (?1§) the line is about, a proposal for instance.
F localerequiredLanguage of the line. On the series it sets the language of the question and of the answer; empty on an item = those languages.
G valuerequiredThe content: title, instruction, question, accepted answer (one per line)… in Parrot Markup.

6. The course

The lessons file describes the outline: a chapter (_), then its lessons. A lesson strings together, in line order, its notes (note) and series (exercise), and declares its vocabulary (vocabulary, by meaning reference).

en/at-the-cafe/lessons/course.csv — download

In a spreadsheet
ABCDE
1chapterlessonattributelocalevalue
2at-the-cafe_titleenAt the café
3frAu café
4order1
5orderingtitleenOrdering and paying
6frCommander et payer
7noteencourse/at-the-cafe/ordering.md
8exercisecafe-translate
9exercisecafe-fill-in
10vocabularycoffee
11tea
12water
13croissant
14sugar
15bill
16waiter
17order
18pay
19the-bill-please
The same file as text: one line per row, cells separated by ";" (same colour = same column)
chapter;lesson;attribute;locale;value
at-the-cafe;_;title;en;At the café
;;;fr;Au café
;;order;;1
;ordering;title;en;Ordering and paying
;;;fr;Commander et payer
;;note;en;course/at-the-cafe/ordering.md
;;exercise;;cafe-translate
;;exercise;;cafe-fill-in
;;vocabulary;;coffee
;;;;tea
;;;;water
;;;;croissant
;;;;sugar
;;;;bill
;;;;waiter
;;;;order
;;;;pay
;;;;the-bill-please
The columns
A chapterReference of the chapter, on its first line. Optional: by default, taken from the title.
B lessonrequired_ = the chapter itself; otherwise the reference of the lesson. Empty = same as the line above.
C attributerequiredtitle, order (rank), note (course sheet), exercise (series), vocabulary (meaning). Empty = same as the line above. The export adds id: the internal identifier, which finds the object again on reimport; not to be written by hand.
D localerequiredLanguage of the line, for a title or a course sheet. Empty otherwise.
E valuerequiredDepending on the attribute: the title, the rank, the path of the sheet in resources/, the reference of the series or of the meaning.

The note is a self-contained Markdown file. Its header declares the language of the material — French here — so that the terms in italics *…* can be heard with a tap. Examples are quotes >: the sentence, then its translation.

en/at-the-cafe/resources/course/at-the-cafe/ordering.md — download

---
lang: fr-FR
---
# Ordering and paying

**1** To order politely, say ***Je voudrais…*** (I would like…) rather than *Je veux…* (I want…), which sounds abrupt:

> *Je voudrais un café, s'il vous plaît.*
> I'd like a coffee, please.

> *Un croissant, s'il vous plaît.*
> A croissant, please.

**2** To pay, ask for ***l'addition*** (the bill). The waiter is addressed as *Monsieur* or *Madame*, never as *garçon*:

> *L'addition, s'il vous plaît !*
> The bill, please!

**3** You will often hear *Et avec ceci ?* (Anything else?). To say no: *Non, ce sera tout, merci.*
A note as the app shows it
A note as the app shows it

7. Import and fix

  1. Zip the folder (or rename the archive to .parrot) and open it in Super Parrot: … menu › Import….
  2. Analyse shows the preview and any errors. Fix, analyse again, then confirm.
  3. To enrich the dictionary later, re-import new files as a complement from the dictionary: a new language, a new chapter… Existing objects are found again and your training results are kept.
  4. For deeper changes, export as CSV 🔒, edit in the spreadsheet and re-import as a complete version.

The column-by-column reference and the finer rules (references, identifiers, updates) are in CSV file reference.