Getting started

← Guide index · 中文

Settings contains an optional shared-account panel. Qonlang and Qonsona use the same account; signing in does not control access to local projects.

1. Installing and launching {#1-installing-and-launching}

All the installers are on GitHub Releases. GitHub can be slow or unreachable on some networks, so please make sure you can reach it before downloading.

Windows: Qonlang-<version>-setup.exe. You can choose the install folder; the desktop shortcut is called 千语集 (Qonlang). The installer is not signed: if your browser says the file isn’t commonly downloaded, choose Keep in the download list; if the first launch shows Windows protected your PC, click More info, then Run anyway. The data folder is %APPDATA%\Qonlang (preferences, recent projects, automatic backups and downloaded fonts all live there).
macOS: Qonlang-<version>-mac-arm64.dmg (Apple silicon) or -x64.dmg (Intel); open it and drag Qonlang into Applications. The app is not signed or notarised, so macOS blocks the first launch:
- macOS 14 and earlier: right-click Qonlang, choose Open, then click Open in the dialog.
- macOS 15 and later: double-click Qonlang once (click Done when it says it can’t be opened), then open System Settings → Privacy & Security, find the message about Qonlang being blocked near the bottom, click Open Anyway and enter your password.
- If it says the app is damaged and can’t be opened, run xattr -cr /Applications/Qonlang.app in Terminal, then open it as usual.
The data folder is ~/Library/Application Support/Qonlang.
Linux: Qonlang-<version>.AppImage. After downloading, tick Allow executing file as program in the file’s properties (or run chmod +x Qonlang-*.AppImage), then double-click it. On Debian or Ubuntu you can use the .deb package instead (sudo apt install ./qonlang_<version>_amd64.deb). The data folder is ~/.config/Qonlang.
From source: after git clone, on Windows double-click dev.cmd in the repository (it bypasses PowerShell, so execution policies don’t get in the way); on macOS / Linux run sh dev.sh. The first run installs dependencies with npm install automatically.

For every release, GitHub Actions builds the Windows installer, the macOS dmg and the Linux AppImage and deb together when the version tag is pushed, and attaches them to the same Release. Versions with -beta in them (such as 1.0.0-beta.1) are test builds, marked Pre-release on the Release page: installs of a regular release are not offered them, so download one from the Release page if you want to try it; once you have a test build, later test builds and regular releases are offered as usual.

On first launch the interface language follows your system: if the system language is one of the nine interface languages it is used, otherwise English. You can change it at any time under Language at the bottom left of the start page.

If Windows says “running scripts is disabled”, that is PowerShell’s execution policy blocking npm.ps1; use dev.cmd, or just run the exe.

2. The start page

The left column of the start page is how you get going; the middle is your projects and the games. The wordmark at the top left follows the interface language: Simplified Chinese, Traditional Chinese, English, Russian and Arabic each have their own, and the other interface languages use the English one.

Sentence of the day: the strip at the top, showing example sentences, phrases and words with images from your recently opened projects (up to 3), one card at a time. Sentences and phrases get a gradient background; a word with an image uses that image, blurred, as its background. Arrows appear at both sides when you hover; click one to move to the next card. The order is shuffled by the date, so the first card stays the same all day. When the language has a script, the card also carries a line above the text with the words written in that script (through its mapping rules, in that script’s font) — one line per script, and the card grows to fit. The small icon at the top left says whether this is a sentence, a phrase or a word with a picture, the top right says Sentence of the day (Word of the day for a picture), and the credit at the bottom right names the language it comes from (project · language). Sentences and phrases keep their original punctuation, and any word in them can be hovered to show its word card — words are recognised exactly as on the Corpus page (words joined by boundary symbols and affixes are recognised, analyses that don’t point to an entry are resolved from forms, paradigm affixes and segmentation, and each segment can be clicked); Open in lexicon on the card opens that project first and then jumps to the word. If a word in a sentence was matched to the wrong entry, click Fix: it likewise opens the project, jumps to that sentence in the corpus and lets you pick the right word (see Corpus · Hover cards). The gallery is hidden when none of the recent projects has anything to show (or you haven’t opened a project yet).
Starter templates (they drop down when you click New project on the left):
- Blank, single language: one language from scratch — the usual choice for an a priori language.
- Language family: a proto-language plus any number of daughter languages (one name per line); later you derive words from the proto-language with sound changes.
- Import from Lexicanter: reads a .lexc file and brings in the lexicon, senses, dialects, pronunciation rules, alphabet, etymologies, phrasebook and docs in one go.
- Import from CSV: creates a blank project and opens the CSV column-mapping wizard.
Recent projects: four per row, at most two rows (eight); one card per project you opened recently, with its name and author, and a word written in that project’s own script at the bottom right (files are read one at a time, so the cards appear first and the writing follows; whichever end overflows fades out, downwards for vertical scripts). Hovering a card lights it with a sheen that follows the pointer; click to open it.
Games: a row of four games under the recent projects, all built from your own lexicon. Click one, pick a project (read only — it is not opened and not changed), then pick a language:
- Flashcards: word on the front, meaning on the back; click to flip, or turn the pair around (meaning first). Answer Knew it / Didn’t know; the ones you missed come round again at the end of the round.
- Sage (the game of that name on elfdict): a few meanings at the top and a pile of letters below — exactly the letters those words are made of. Tap letters to spell a word, tap a chosen letter again to take it back; the bulb next to a line reveals that one answer.
- Word guess: six tries. Letters are judged by this language’s alphabet, so th or ll count as one square; word length 3–7. Green is the right place, amber is in the word but elsewhere.
- Crossword: a grid built from the lexicon with the definitions as clues. Check marks what you have, Reveal fills it in; Export web page writes a single .html anyone can open in a browser to play, check and print (or save as PDF), and Export image gives the empty grid with the clues, for printing.
Recent: the list at the bottom of the left column; files that no longer exist are removed from it automatically.

The left column also has New project, Open project, Example projects and User guide. Example projects contains two fictional projects that, between them, show every module — the quickest way to see what a feature looks like and how its data should be filled in:

Aelith (an agglutinative a priori language): a proto-language → modern language family with a sister language, Merun (compare cognates in the relation graph), vowel harmony, multi-slot suffixes, all eight kinds of pipeline steps, variants and inheritance, disabled slots and hand-filled tables, sandhi voicing that applies to all words (with classes declared inside the tweak step), compound parts of speech, inspector modules, etymology chains and the relation graph, images and dialects, a glossed and confirmed corpus with punctuation, a runic script, features and stress rules (plus a merger of two sounds: t and d both become r between vowels), a custom stress rule, entries with Affects stress, the family node “Ael 语系” with group statistics, the historical stages CAe → Ae with each entry’s history (kaso: PAe kasu → CAe kaso → Ae kaso), plural cases based on 复数.主格 (plural nominative), locative slots that affect pronunciation (kasoda reads ˈkasoða), an allomorph picked by a grammatical value (the plural marker is -lAn before the dative: kasolanka), and the verb’s third-person cells deliberately left empty so that, in simple mode, they continue from the 极性.时 (polarity-tense) slots.
Tsahun (an isolating tone language): five tones, romanised and Cyrillic orthographies (syllables and sound counts follow the spelling), syllabary packing and vertical text, reduplication paradigms and inflected forms containing spaces, homograph candidates, a variant-character module, a logographic script written from glyph codes, classifiers and a whole borrowed numeral system.

When the interface isn’t Chinese, the documents in the example projects (About this example, the grammar sketches and so on) open in English; the example data itself — entries, sentences and so on — stays the same.

Each example card has Open and Make a copy. Open is for trying things out: change anything, but it can’t be saved — the top bar shows an Example badge and Make a copy where Save would be, Ctrl+S only shows a hint, nothing is marked as unsaved, and closing never asks. Make a copy (on the example card, or in the top bar once opened) asks where to save a copy, and that copy is your own normal project that saves as usual.

The six buttons at the bottom are Buy me a coffee, Changelog (the repository’s CHANGELOG.md, or the English CHANGELOG.en.md when the interface isn’t Chinese), Developer, Friends, Credits and Rule syntax, each shown in the right-hand panel when clicked (when the start page opens, that panel shows the changelog); the Developer panel starts with Report a problem and Copy diagnostics (see Settings · About); to their left is User guide, which is this site.

Three more sit at the bottom left: Language (the interface language), Theme (light or dark, and Theme presets) and Settings (the Application half of Settings — everything that isn’t about a project) — all available without opening a project.

3. The project file

One project = one *.laim.json file, containing all languages, rule sets, parts of speech and dimensions, morphemes, entries, paradigms, sentences, phrases, abbreviations, doc pages and project settings. Fonts embedded in scripts are stored inside it too (as data URLs), so the project still displays correctly on another computer.
Settings → Export as folder: one JSON per collection, rule sets additionally as plain text, and doc pages as .md — convenient for keeping in git and reading diffs.
Autosave: the interval set in Settings (in seconds; 0 turns it off). Independently, a snapshot is written to the data folder every 5 seconds, so after a crash the app offers to restore it on the next start.
Backups: before every save, the previous file is copied to Backups/ in the data folder; the last 20 are kept by default.
Close protection: if there are unsaved changes when you close the window or click 千 in the navigation bar to go back to the start page, a prompt lets you save or discard.
Checking for changes made elsewhere: before saving (autosave included), Qonlang checks whether the file was changed by another program since you opened or last saved it — another Qonlang window, a cloud-sync folder and so on. If it was, you are asked first: Overwrite replaces those changes with what you have now; Save as… saves to another file and leaves the original alone; Don’t save yet writes nothing this time and pauses autosave, and Ctrl+S lets you choose again.
Two copies of Qonlang at once: that’s fine; the one opened second first tells you Qonlang is already open. Please edit a project in only one window; each window keeps its own crash-recovery snapshot, so they don’t overwrite each other.
Format promise: from 1.0 on, every later version can open project files saved since 1.0 (read-only copies included).

4. A suggested order for building a language

Languages: check the language name, abbreviation and colour; for a family project, get the tree right first.
Phonology: build the phoneme inventory from the IPA chart, generate the C / V classes with one click, and write the “orthography → IPA” rules.
Lexicon: enter a first batch of words (or import from CSV / Lexicanter); parts of speech and dimensions are defined on the Parts of speech & dimensions sub-page.
Morphemes: roots and affixes.
Paradigms: combine dimensions into slots, write generators, bind parts of speech and write the derived forms.
Sound changes (family projects): rule sets, stages bound to languages, evolving the lexicon.
Script: if the language has its own writing system.
Corpus: gloss example sentences automatically; confirmed analyses become the first choice in other sentences.
Docs / Phrasebook: grammar notes and common phrases.
Lexicon → Export: dictionary as HTML / Markdown / PDF.

None of this order is enforced — you can go back to any page at any time, and everything that depends on it updates automatically.

5. The top bar

The project name and a Saved / Unsaved badge, followed by the search box (its placeholder follows the current module, and it clears when you switch pages).
Current language drop-down: most pages only show data for the current language; choose All languages to see the whole project. New content in the Corpus, Phrasebook, Docs and similar pages belongs to the current language by default.
Buttons for saving (Make a copy for an example project, see above), showing the inspector and closing the project.

6. The web version

The same code can be built into a static site with npm run build:web. In the browser it reads and writes local project files through the File System Access API and keeps snapshots and fonts in IndexedDB. Everything works the same, except that PDF export goes through the browser’s print dialog.