# ArtGram Language Aptitude Task

Learn vocabulary and grammar of an artificial language, then translate sentences. The task has two phases: a 3-minute vocabulary study phase where participants memorize word-image associations via a single reference slide, followed by a translation test with multiple-choice trials in which participants select the correct translation (French, English, or German) of an ArtGram sentence. A 15-minute global time limit spans both phases, and the vocabulary reference remains visible during the test.

Part of the NCCR Evolving Language task library (University of Geneva). Built by GitLab CI and packaged as `task.zip` + `dist/` artifacts, which the library SPA pulls in via `npm run registry:sync`.

## Requirements

- A modern browser (Chrome, Firefox, Edge, or Safari) with JavaScript enabled.
- A local HTTP server for development (e.g. `python3 -m http.server`, `npx serve`, or any static server). Opening `index.html` directly with `file://` is not recommended because the stimulus image is loaded via a relative path.
- No Node, build step, bundler, or package manager. All scripts are plain ES5-compatible JS included via `<script>` tags.

## Install

```bash
git clone <repo-url> artgram-language-aptitude-task
cd artgram-language-aptitude-task
```

No dependencies to install.

## Run

From the task root, start any static HTTP server and open the served URL:

```bash
# Option 1: Python 3
python3 -m http.server 8000

# Option 2: Node (no install needed)
npx serve .
```

Then open `http://localhost:8000/` (or the URL shown by `serve`) in a browser. The task starts on the instructions screen; click **Begin** to launch the 15-minute global timer and the 3-minute vocabulary phase.

Language (English / Deutsch / Français) can be selected on the instructions screen via the dropdown; the choice is persisted in `localStorage` under `task_lang`. The switcher is hidden once the task starts.

## Controls

Mouse / touch only — there are no keyboard shortcuts.

- **Begin** — starts the global 15-min timer and the 3-min vocabulary phase.
- **Continue to Test** — ends the study phase early and advances to the translation test.
- **Option buttons (4 per trial)** — click to select a translation. The answer is locked in on click; correct feedback is shown and the correct option is highlighted green before advancing.
- **Download Results (CSV)** / **Download Results (JSON)** — shown on the completion or time-expired screen.

## Outputs

- **Aim:** measure artificial-language learning aptitude (grammar-rule induction and sentence translation).
- **Storage:** browser-local only — nothing is sent to a server. Participants (or experimenters) click one of the two download buttons at the end to save the file locally.
- **Formats:**
  - CSV — one row per trial.
  - JSON — array of trial objects.
- **Design:** trial-based; trial count is driven by the embedded `TRIALS_ALL` table (12 trials per language in the current build).
- **Per-trial variables:** `trial_number`, `artgram_sentence`, `option_1`..`option_4`, `selected`, `correct_answer`, `accuracy` (0/1), `rt_ms`, `time_remaining_sec`, `lang`.
- **Derived measures (not computed in-task, suggested for analysis):** overall translation accuracy (%), mean RT for correct translations, learning curve across trial blocks.

## Files

```
.
├── index.html             # Single-page task: screens, styles, inline TRANSLATIONS + TRIALS_ALL, main script
├── task.json              # NCCR library metadata (id, description, variables, outputs, contact)
├── .gitlab-ci.yml         # CI: zips all non-meta files into task.zip + dist/ artifacts
├── js/
│   ├── data-collector.js  # Row collector with CSV/JSON download helpers
│   ├── timer.js           # TaskTimer: countdown + per-trial RT measurement
│   ├── trial-engine.js    # Trial sequencing, onTrialStart / onTrialEnd / onComplete hooks
│   └── lang-switcher.js   # Runtime EN/DE/FR switching via data-i18n attributes
└── stimuli/
    ├── Slide1-09-22-21_19-15-19-709.jpg   # Vocabulary reference slide (study phase + test-phase reference)
    ├── Artgram deepl 1.mp3 … 4.mp3        # Audio narrations (bundled; not wired into index.html in this build)
    ├── Artgraminstrscreen1.mp3            # Instruction narration (bundled)
    ├── Artgramlearnscreen1.mp3 / 3.mp3    # Learn-screen narrations (bundled)
    └── instructions_placeholder.mp3       # Placeholder narration (bundled)
```

Note: the audio assets ship with the task but are not referenced by `index.html` in the current build; they are retained for future phases or localised narration.

## Contact

Narly Golestani — narly.golestani@unige.ch
[Brain and Language Lab](http://brainandlanguagelab.org/)
