CollationKit
Scholarly textual collation for editions and translations. It finds every insertion, deletion, substitution and moved passage, and cites each one by page, line and word.
What it is
Scholars who study a work that survives in several forms (a manuscript, corrected proofs, a first edition, a revised edition, rival translations) need to know precisely how those versions differ. This is textual collation, and its product is an apparatus criticus: a citable record of every variant.
CollationKit is a deterministic, pure-Swift engine for that job. Given several witnesses of one work, it reports each difference as a typed variant, including passages that moved across a page boundary. Every finding carries a citation. It separates substantive changes of wording from accidentals (spelling, punctuation, case). It merges many witnesses into one variant graph, with or without a privileged base text, and can anchor witnesses across languages.
It ships with the collate command-line tool, a self-contained interactive HTML viewer, a
language-neutral conformance corpus with a JSON Schema, and complete novels in rival translations for
evaluation.
Why not diff?
Words, not lines
Prose reflows and revision happens at the level of the phrase. Needleman–Wunsch alignment over tokens makes a reworded clause one substitution, not a deleted block plus an inserted one.
Moves are moves
A passage relocated across a page, even one revised in transit, is reported once as a transposition,
with certain or likely confidence.
Not every difference matters
Substantive variants are separated from accidentals, so a GB/US spelling doesn't drown the finding. Accidentals can still be recorded for a diplomatic view.
A citation, not a patch
Every variant is located as p. 2 · line 1 · words 1–10, under an explicit pagination
model.
Example
From the located variant report for the bundled six-edition example, comparing the manuscript (MS) with the Uniform edition (UNI):
$ collate run MS.txt UNI.txt MS vs UNI: 5 variant(s) [1] TRANSPOSITION (moved) (ACROSS PAGES) MS: “The lamps were lit along the quay one by one” @ p.2 · line 1 · words 1–10 UNI: “The lamps were lit along the quay one by one” @ p.1 · line 2 · words 1–10 … [4] SUBSTITUTION MS: “tired” @ p.1 · line 2 · word 3 UNI: “weary” @ p.1 · line 3 · word 3 [5] SUBSTITUTION MS: “cold” @ p.2 · line 2 · word 2 UNI: “bitter” @ p.2 · line 1 · word 2
A line diff would report the moved sentence twice: as a deletion on page 2 and an unrelated insertion on page 1.
Demos
Each demo is the interactive viewer exactly as collate exports it: one self-contained HTML file
with an overview, the annotated text of each witness, a variant graph, parallel columns, a redline of changes,
a prose story of the differences, an alignment map and a traditional apparatus.
Six editions of one passage
Manuscript to Uniform edition, with a sentence moved across a page. The worked example behind the tests.
Frankenstein, 1818 / 1831
Mary Shelley's revision, with punctuation and spelling variants recorded alongside substantive ones.
Whitman, “Song of Myself”
The opening stanzas of Leaves of Grass in 1855, 1860 and 1891, merged into one variant graph.
Whitman, “Calamus”
A genuine authorial relocation of a whole poem between 1860 and 1867, recovered as a single move.
Verne in three voices
The French original and two English translations, aligned with the peer merge and a small lexicon.
Journey to the Centre of the Earth
Two Victorian translations of chapter 1. Even the professor's name differs: Liedenbrock or Hardwigg.
Complete novels (100–200k words per witness) collate in seconds with a release build, but
their viewers run to tens of megabytes, so they aren't hosted here. To reproduce one, run
collate run corpus/verne/journey-centre-earth/full/{malleson,ward}.txt --out results.
Get started
Requires macOS 13 or later and Swift 5.9+ (Xcode 15 or later). No third-party dependencies.
git clone https://github.com/ancientlives/CollationKit.git cd CollationKit swift test # 222 tests swift build -c release # use release builds for full-length texts .build/release/collate run --dir corpus/verne/journey-centre-earth --all --out results open results/collation.html
collate # interactive menu collate run base.txt witness.txt … # scriptable collate run --strategy peer-msa --lexicon fr-en.lex fr.txt en1.txt en2.txt
Research
The deterministic core is mature and has been evaluated on complete novels in independent translations, on verse, and on non-Latin scripts. The open questions sit above it and around it.
- A semantic layer, carefully gated
- Can learned signals such as sentence-level cross-language anchoring or phrase commonness sharpen alignment and move confidence, while the engine stays deterministic, auditable and faithful to each witness's words?
- The irreducible residual
- Short passages near their original position can't be told from coincidence by geometry alone. Word and phrase rarity have already been shown not to help. What can?
- Visualisation and trust
- Which views do scholars actually rely on? Does the alignment map let a reader verify an alignment? How should calibrated uncertainty be shown to an expert entitled to overrule the tool?
Two papers are in preparation, one on the algorithms and their evaluation and one on visualising collation results. The research introduction gives the full picture.
Documentation
- RESEARCH_INTROWhat the project is and where the research is heading. Start here.
- ONBOARDINGBuilding, running, the code map and a suggested first week.
- ALGORITHMSA language-neutral specification with a porting checklist.
- ALGORITHM_SURVEYEach algorithm's cost and weaknesses, and candidate improvements.
- CASE_STUDYThe engine on Shelley, Whitman, Verne and Pushkin.
- DEVELOPMENT_LOGThe design history, including dead ends and negative results.
- conformance/Golden corpus and JSON Schema for verifying ports.
- INDEXThe full map of the documentation.
Contributing
Code, evaluation texts, bug reports and research questions are all welcome through pull requests. Read CONTRIBUTING.md for the workflow and the engine's invariants. A collation that looks wrong on a real text is useful evaluation data, so please open an issue.
Citing
@software{collationkit, title = {CollationKit: transposition-aware scholarly textual collation}, author = {ancientlives}, year = {2026}, url = {https://github.com/ancientlives/CollationKit} }
Code is MIT-licensed and documentation CC BY 4.0. The literary texts are public domain, except for one short attributed quotation (see LICENSE-docs). Related tools: CollateX, Juxta, and the TEI critical apparatus module (comparison).