CSV file reference
The reference for import files, type by type. For a first approach, start instead from Creating a dictionaryand its example.
Common rules
- Encoding UTF-8 (a leading BOM, as Excel writes, is tolerated).
- Separator
; or tab, detected on the header line. The comma separates multiple values inside a cell
(noun, fem).
- Quotes: a cell containing the separator, a quote or a line break is wrapped in
", and an inner quote
is doubled. Spreadsheets do this for you.
- Header required, exact column names, any order. A missing required column or an unknown column makes the file
invalid: a typo never gets lost silently.
- Ignored lines: empty ones, or those whose first cell starts with
#.
- Booleans:
x = yes, empty = no.
- Clearing a value in a complement update: a cell containing only
~.
- Changing a list in a complement update:
+Travel adds, -Trade removes.
Language codes
- Labels (titles, categories, tags, abbreviations): bare code
en, fr, pt; a regional code
only when it means something.
- Words and exercises: language with country when the dictionary tells them apart (
en-GB, en-US,
fr-FR, pt-BR).
File types
| Type | Folder | Header (required in bold) |
| Dictionary | root, only one | attribute;locale;value |
| Categories | categories/ | reference;parent;locale;category;selectable;optional;description |
| Tags | tags/ | reference;parent;locale;tag;selectable;optional;description |
| Abbreviations | abbreviations/ | reference;locale;abbreviation;categories |
| Patterns | patterns/ | reference;locale;name;prefix;suffix |
| Vocabulary | vocabulary/ | type;reference;locale;text;context;translation_context;ipa;register;frequency;level;categories;tags;pattern;illustration |
| Related meanings | relations/ | meaning;meaning_locale;type;target;target_locale;rank |
| Exercises | exercises/ | topic;item;attribute;section;index;locale;value |
| Course | lessons/ | chapter;lesson;attribute;locale;value |
Exports add an id column (or attribute): the internal identifier, which finds the object unambiguously on re-import.
Don't copy it when you duplicate a line to create a similar object.
Each file is self-contained for its type: a complete branch of a tree, a meaning with all its words, a series with all its items, a
chapter with all its lessons.
Dictionary
| Attribute | Value |
title | title, one line per language |
reference | readable, stable reference |
author, organization | authors (one line each), organisation |
type | DICTIONARY (default) or WORKBOOK (with a course) |
version | content version |
mode | learning (default) or exam; with exam_order
(selection, random) and exam_correction (immediate, end) |
speech_locale | voice that reads a language with no system voice (co → it-IT) |
spoken_abbreviation, spoken_abbreviation_text | how an abbreviation is spoken
(sth: ˈsʌmθɪŋ, sth: something) |
Vocabulary
| Column | meaning line | word line |
| reference | meaning reference, optional (otherwise m1, m2…) | optional |
| locale | — | the word's language, with country |
| text | — | the bare word, or the sentence |
| context | — | main context, in the word's language |
| translation_context | — | translation context, in the language of the person quizzed: en§vehicle |
| ipa | — | IPA transcription |
| register, frequency, level | — | a category of the registre, frequence,
niveau families |
| categories, tags, pattern | — | by reference (recommended) or label |
| illustration | the meaning's picture (path in resources/) | — |
Synonyms are words of the same meaning. Links between different meanings (plural, antonym, derived word) go in
relations/, with the types INFLECTION, OPPOSITE and DERIVED.
Exercises
| Attribute | Series (_) | Item | Role |
title | ✓ | | title, one line per language |
wording | ✓ | ✓ | instruction; on an item, it replaces the series' |
example | ✓ | | example shown |
question | ✓ | ✓ | series: section and language of the question; item: the prompt |
answer | ✓ | ✓ | series: section and language of the answer; item: one accepted answer per line |
proposal | ✓ | ✓ | proposals to tap, one per line |
language | | ✓ | language of the answer when it differs from the series' |
categories, tags | ✓ | ✓ | for filters |
Course
| Attribute | Chapter (_) | Lesson | Value |
title | ✓ | ✓ | title, one line per language (optional for a lesson: its note's title) |
order | ✓ | ✓ | rank; required for the first chapter of each file when there are several |
note | | ✓ | path of a note (.md or .html); one line per language for
versions of the same note |
exercise | | ✓ | a series, by reference or title |
vocabulary | | ✓ | a meaning: its reference, or a word with its language
(bill [at a restaurant]) |
Text: Parrot Markup
Text cells accept a light markup in braces, Parrot Markup; plain text remains the usual case. The essentials below; everything is in Parrot Markup.
| Write | Effect |
{the|}, {colour|color} | alternatives: all are accepted |
{?1§} | a gap to fill (no. 1) in the question |
{?1§bought} | the expected answer for gap no. 1 |
{type=affix§.} | shown but never marked (punctuation, article) |
{type=clue§past tense} | a clue, shown in brackets |
{#1§lang=fr-FR§Il a abandonné.} | a section in another language (a guiding translation) |
ipa=ˈsʌmθɪŋ§sth | forces the pronunciation |
`{` | the backtick escapes a special character |
Course notes in Markdown
---
lang: fr-FR
---
# Title of the note
**1** A paragraph, with a *term* you can hear and some **bold**.
> *Je voudrais un café, s'il vous plaît.*
> I'd like a coffee, please.
## A subheading
| form | meaning |
|---|---|
| *l'addition* | the bill |
- a list
- see lesson (§2.1)
- The
lang header declares the language of the material: terms in *italics* become audible.
*[en-US] sidewalk* marks a regional variant; *schedule /ˈʃɛdjuːl/* adds a pronunciation.
- A
> quote = an example and its translation; one sentence per quote.
(§8.3) refers to lesson 3 of chapter 8 and becomes a link in the app.
- Also accepted:
# and ## headings, tables, - lists, ~~strikethrough~~,
`code`.
Updates
| Mode | Behaviour |
| Creation | from the dictionary list; the Dictionary file is required |
| Complement | files add and change; an empty cell changes nothing; nothing is archived |
| Complete version | files describe everything: an empty cell clears, whatever is missing is archived (and can be restored) |
| Merge | files are poured into another dictionary; shared words are matched; the target dictionary wins on conflict |
An object is found by its identifier, then by its written reference, then by its content (a meaning by its unchanged words, a
corrected word by similarity). That is why references stay optional.