This directory contains the word lists containing the words that are supposed
to be built or guessed. They are specified specified as comma-separated
values (CSV). CSV is a file format specified in RFC 4180
<https://www.rfc-editor.org/rfc/rfc4180>.

Each word list file follows the naming scheme <name>_<language>.csv, where
<name> is the name and <lang> the language code.

## Columns

Each row has exactly 6 columns. Their meaning is slightly different for the
English and the translated word lists.

The columns for the English word list are translations as follows:

1) Primary word
2) Context (may be empty)
3) (empty)
4) (empty)
5) Synonyms for the primary word (may be empty)
6) (empty)

The columns for the word lists in other languages are as follows:

1) English primary word
2) Context for the English primary word (may be empty)
3) Translated primary word
4) Context for the translated primary word (may be empty)
5) Synonyms for the translated primary word (may be empty)
6) Flags (may be empty)

Columns 1 and 2 are special because they not only are the English primary word
and optional context, but they together also uniquely identify an entry across
all languages.

A detailed description of all columns follows:

### Column 1

The English primary word is the word (or term) that is shown to the artist and
to guessers after the round. If a word has are synonyms, the primary word
should be the word that is the most recognizable to the majority of speakers.
This also should be kept as short as possible.
If the concept is primarily known only by an acronym, use the acronym here,
and add the expansion of the acronym into the synonym list.
Note this does not necessarily have to be literally only 1 word.
Multiple words are allowed.

Column 1 must be the exactly the same in both English and translated word lists,
because it is used to identify entries.

It is allowed for the same English primary word to be used twice, but then all
such entries MUST use the English context column.

Column 1 must be the exactly the same in both English and translated word lists,
because it is used to identify entries.

### Column 2

The context for the English primary word must be used when the English primary word
without context would be ambiguous or has multiple common (!) meanings in everyday language.
The context should generally be like 1 to 3 words to point at the category.
It should *not* be a description or definition.

If the English primary word mostly unambiguous, this column should be empty.
Only add context if its necessary. Context needs only to be given to the *primary*
word (if at all). The synonyms do not matter.

For the default word lists, if a obscure technical or scientific interpretation of a term
exists, it does not as a "common meaning". You don't need to add context for every
common word if it also has some obscure technical or scientific meaning.

It is allowed (and encouraged) to add the same English primary word multiple times,
but with different contexts. English is notoriously a pretty ambiguous language
where words often have many contradicting meanings, so context is important.

Example:

The word "spring" could mean the mechanical device, a water source, or a season.
An appropriate context fields would thus be "device", "water source" or "season",
depending on which of the three you meant.

The word "apple" is clear enough in everyday use that no context is needed.
The context field should thus be empty.

### Column 3

This column is only used in translated word lists and empty in the English word list.

It is similar to column 1, but for the translation.

The translated primary word is the primary word that is prominently shown to the artist
and in the solution to players who play with a QuikBild language other than
English.
Mostly the same rules as for column 1 apply here, except they're for the translated word.

### Column 4

This column is only used in translated word lists and empty in the English word list.

It is similar to column 2, but for the translation.

It contains the context of the translated primary word. If the translated
primary word is ambiguous, a context should be given here. The same
context rules as for the context of the English primary word
apply here.

### Column 5

This column is a list of synonyms of the primary word, if any.

If the primary word is known by a synonym or multiple synonyms
of that language, this column should list each synonyms here.
Multiple synonyms must be separated by "|".

All synonyms of the primary word will score. The player
gets the point if they either guess the primary word or *any* of
the synonyms in their current QuikBild language.

For the English word list, the synonyms are for the English primary word (column 1).
For the translated word lists, the synonyms are for the translated primary word (column 3).

Only add synonyms if they are relatively known. A bit unknown is also OK.
Obscure technical and scientific synonyms are discouraged, unless its an expansion
of an acronym.

The list can be as long as you like. The goal of the synonyms is to make guessing
more fair. The idea is that players generally get the "win" as soon they guessed the right
*concept* without having to keep guessing randomly from a long list of synonyms which
will cost precious seconds.

 If the primary word is an acronym, the expansion
of the acronym should be added here.

Example: 

For "rabbit", the synonym "bunny" could be used.
For "litter", the list of synonyms may be "refuse|waste|trash|garbage".


### Column 6

Column 6 is for flags, which is a set of special properties to add to the word,
separated by "|" each.
Currently, only one flag is supported: "fuzzy"

If this column contains the "fuzzy" flag, then this means the translation of the
word is incomplete and needs to be updated by translators. If the translation
has been verified to be good, the fuzzy flag should be removed.
If *any* translation of a word is marked as fuzzy, then the word will not be
played in QuikBild.

This flag is not permitted in the English wordlist and will be ignored.

More flags may be added in future versions.

## Escaping

If for some reason you must write a literal "|" or "\" in any cell, you must write it differently:

* To add a literal "|", you must write "\|" instead
* To add a literal "\", you must write "\\" instead

This is known as "escaping".


## Word guidelines

Please follow the following guidelines for all words:

1. Try to keep the primary word short
2. For English words, British English is preferred
3. Only use one entry per concept. If the same concept is known by different words, all words must be in the same entry, using synonyms
4. Using multiple words in the primary word or synonyms is allowed, but try to use a single word as often as possible
5. Newline characters are forbidden
6. If you added the same English primary word multiple times, you *must* fill in the context field for each entry

### Default word list guidelines

For the default/built-in word lists, we follow this extra guideline:

Words that refer to animals should generally be considered with a *broad* interpretation rather than refer to exact an species, unless a particular species is very iconic. Animal words follow *colloqial* use rather than a scientific use.

Animal words should also be chosen based on how distinguishable they are from each other to make it easier to build and guess. When different animal words would end up to look too similar when actually built, it makes sense to use words more broadly.

For example, the word "crocodile" in colloqial use may refer to animals of the family Crocodylidae) but more broadly, it may refer to *any* member of the order Crocodilia which includes alligators (genus alligator) and caimans (genus Caiman) and many other animals. For QuikBild, this means it makes sense to use the word “crocodile” and add “alligator” as a synonym (rather than its own word).


## Maintenance

You may want to add or remove words from time to time. The recommended method to do so is as follows:

## All changes

1. Perform the change or changes on the English version of the word list (see below)
2. Run `update_wordlist_translations.lua` with a Lua interpreter (read the source code comment in this file for details)
3. Review the changes
4. If the changes look good, commit them

### Adding a word

Add a new row into the *English* version of the word list you want to edit. Add the primary English word
and, if needed, an English context. Make sure to avoid a duplication in the word list. Also look up the
word in dictionary for any possible English synonyms.

### Removing a word

Simply remove the row of the word you want removed from the *English* version of the word list.
