# Annotation Tool for Linguistics and Language Documentation

Source: https://www.potatoannotator.com/use-cases/linguistics

**Potato imports texts from FLEx and Toolbox and recordings with Praat TextGrid or ELAN tiers, puts each sentence or interval in front of reviewers with checks against the Leipzig Glossing Rules, and exports the corrected analysis back to the source tool. Potato is free and open source and runs on your own computer or server, including a laptop in the field.**

In a documentation project the first analysis usually exists already, in a FLEx database, a Toolbox file, or a set of TextGrids, and the remaining work is checking that analysis, often with several people sharing the texts. Tools that do both glossing and collaboration are scarce. A 2026 survey of 98 annotation tools for language documentation found that of the 44 that are free and accessible, 15 support morpheme segmentation and glossing, and 6 combine morphological annotation with remote collaboration at no cost ([Yang et al., 2026](https://aclanthology.org/2026.computel-1.9/)). Potato covers the review step. Potato assigns texts to reviewers, checks the alignment of every word, and records who confirmed each sentence.

## Linguistics tasks in Potato

Each row below is a task type Potato ships with, and the linked page has its full configuration.

| Task | How Potato does it | Docs |
|---|---|---|
| Check and correct interlinear glosses | An `interlinear_gloss` scheme marks every word whose morpheme segmentation and gloss do not line up | [Interlinear glossed text](/docs/annotation-types/interlinear-gloss) |
| Correct time-aligned transcripts | TextGrid and `.eaf` files import as tiers of a `tiered_annotation` scheme, one segment per interval | [Transcript formats](/docs/annotation-types/transcript-formats) |
| Draw-a-map tasks | A `geo_annotation` scheme with `task: draw` on your own outline map, aggregated by the `geo_overlap` export | [Perceptual dialectology](/docs/guides/perceptual-dialectology) |
| Reading-time experiments | Self-paced reading (moving window, cumulative, centered) and the A-maze task, with a time for each region | [Self-paced reading](/docs/experiments/self-paced-reading) |
| Judgments of speech samples | `listening_test` schemes for MUSHRA, ACR, and ABX tests with blinded stimuli | [Listening tests](/docs/annotation-types/listening-tests) |
| Acceptability and rating tasks | Likert, slider, and best-worst scaling schemes over sentences or audio | [Likert scales](/docs/annotation-types/likert-scales) |
| Corpus annotation | Span labels for entities and other spans, exported as CoNLL-2003 or CoNLL-U | [Span annotation](/docs/annotation-types/span-annotation) |

## A glossing review project

The scheme below reads a sentence and any existing segmentation and glosses from each item, and the reviewer corrects the segmentation and glosses. `abbreviations: leipzig` warns when a category label is not one of the Leipzig abbreviations, and `tiers` adds extra lines under each word.

```yaml
annotation_task_name: "Glossing review"
task_dir: "."
data_files:
  - data/sentences.jsonl
item_properties:
  id_key: id
  text_key: text
output_annotation_dir: annotation_output/
user_config:
  allow_all_users: true
num_annotators_per_item: 2    # two reviewers per sentence
annotation_schemes:
  - annotation_type: interlinear_gloss
    name: igt
    description: Segment each word into morphemes and gloss every morpheme
    source_field: text
    morphemes_field: morphemes
    gloss_field: glosses
    translation_field: translation
    tiers: [pos]
    abbreviations: leipzig
    language: la
    metalanguage: en
```

Two reviewers per sentence (`num_annotators_per_item: 2`) gives a second opinion on every gloss, which is the usual trade-off when a team is checking a consultant's texts. Set `num_annotators_per_item` to 1 when each text has a single responsible reviewer. In practice you rarely write the config by hand, because `potato import` writes the config from a FLEx or Toolbox file.

## Bringing texts in and taking them back out

`potato import` turns a FLExText file, a Toolbox database, or a folder of TextGrid or ELAN files with their recordings into a runnable project. Each phrase, record, or recording becomes one item, and the existing analysis is loaded as its starting point.

```bash
potato import -i stories.flextext -o glossing-project/
potato import -i texts.txt -f toolbox -o glossing-project/
potato import -i recordings/ -o transcripts-project/
```

The export writes the corrected work back in the same formats: `flextext` and `toolbox` for glosses, `igt` for aligned plain text and gb4e LaTeX, and `textgrid` and `eaf` for tiers. Re-importing an exported FLExText file gives the same words, segmentations, glosses, translations, and parts of speech. FLEx GUIDs and lexicon links are lost on the way back, because the export has no lexicon. [Linguistic fieldwork](/docs/guides/linguistic-fieldwork) lists the rest of what does and does not round-trip, and [Export formats](/docs/features/export-formats#linguistics-and-speech) lists the files each format writes.

## Working alongside FLEx, ELAN, and Praat

Each of these tools has a different job, and Potato is built to sit between the three. [FieldWorks Language Explorer](https://software.sil.org/fieldworks/) contains the lexicon and the morphological parser. [ELAN](https://archive.mpi.nl/tla/elan) does multi-tier, time-aligned annotation of audio and video, and [Praat](https://www.fon.hum.uva.nl/praat/) is a program for phonetic analysis. When several people check the same material, Potato adds assignment of texts to reviewers, a record of each person's answer, and a web interface, so reviewers need not install the analysis software.

The web interface also matters for platform. Current FLEx releases run on Windows, [not on macOS](https://knowledgebase.arts.ubc.ca/?p=4808), and SIL [no longer supports](https://software.sil.org/fieldworks/download/) the Linux version. Potato installs on macOS, Linux, and Windows, and reviewers use a browser. A reviewer on a Mac can check texts exported from FLEx without a virtual machine.

## Frequently asked questions

### Can Potato import ELAN and Praat TextGrid files and export them back?

Yes. `potato import` reads `.TextGrid` and `.eaf` files that have an audio or video file of the same name beside each one, and each tier becomes a tier of one `tiered_annotation` scheme with one segment per non-empty interval. The `textgrid` and `eaf` exporters write the corrected tiers back out. Potato reads TextGrids in UTF-8 and in UTF-16, the encoding Praat often uses.

### Does Potato run on a Mac?

Yes. Potato is a Python package that installs with `pip install potato-annotation` on macOS, Linux and Windows, and annotators work in a web browser. A Mac user can review texts exported from FLEx, which does not run on macOS.

### Can Potato run in the field without an internet connection?

Yes, once Potato is installed. Potato serves every script, stylesheet, and font from its own install, and the draw-a-map task fetches no map tiles, so a laptop with no connection runs the same interface. [Air-gapped deployment](/docs/measurement/air-gap) describes what is served locally.

### Can I run a draw-a-map task online?

Yes. The `geo_annotation` scheme with `task: draw` shows participants an outline map you provide as GeoJSON, and participants outline and name the areas where people speak differently in their view. The `geo_overlap` export overlays all participants' drawings as heat maps. [Perceptual dialectology](/docs/guides/perceptual-dialectology) walks through a complete example study.

## Further reading

- [Linguistic annotation tools compared](/docs/guides/linguistic-annotation-tools-compared), for FLEx, ELAN, Praat, and other language documentation tools
- [Linguistic fieldwork](/docs/guides/linguistic-fieldwork), for the FLEx, Toolbox, Praat, and ELAN workflow end to end
- [Multilingual and low-resource annotation](/docs/guides/multilingual-low-resource-annotation), for annotating in many languages and scripts
- [Inter-annotator agreement](/docs/guides/inter-annotator-agreement), for measuring how far two reviewers agree
- [Audio and speech](/use-cases/audio-speech) and [psychology experiments](/use-cases/psychology), for neighboring fields on this site

## References

1. Yang et al. (2026). Annotation Tools for Language Documentation: A Survey of Capabilities, Gaps, and Morphological Support. *Proceedings of the Ninth Workshop on the Use of Computational Methods in the Study of Endangered Languages (ComputEL-9)*. https://aclanthology.org/2026.computel-1.9/
2. Comrie, Haspelmath, and Bickel. The Leipzig Glossing Rules. Max Planck Institute for Evolutionary Anthropology. https://www.eva.mpg.de/lingua/resources/glossing-rules.php