Qingjian: a Rust pinyin IME that puts a translation beside every candidate

What Qingjian is trying to fix about learning vocabulary while typing

The README opens with a question rather than a feature list: why should learning a language require opening a separate study application? Its answer is that people already spend much of the day typing, in chat, in code, in search boxes, in notes and documents. Qingjian attaches a small translation to each candidate so that a fraction of that typing time doubles as vocabulary exposure.

The example the README gives is a Chinese speaker learning English. Type a pinyin syllable and the candidate window shows the Chinese word with a smaller English gloss beside it, for instance 开发 next to development, 编程 next to programming, 架构 next to architecture. The candidate remains the primary element; the gloss is deliberately rendered as secondary text.

That constraint is the most interesting design decision in the project. Qingjian only ever shows one auxiliary language at a time. The README states it will not place English, Japanese, Korean and German around a single candidate, on the grounds that a clean typing experience matters more than showing more information. The learning language is a setting, not a per-candidate property, and the .env.example file shows the accepted values as en, ja and es.

The intended audience is narrow and specific: people who type Chinese daily and are studying one other language, on macOS or Windows. It is not aimed at professional translators, and it is not a flashcard application.

The core is platform-independent and the shells are thin

Cargo.toml lays out the architecture more clearly than the README does. The workspace splits into crates/qingjian-core, qingjian-dictionary, qingjian-translate, qingjian-learning, qingjian-platform, qingjian-predict, qingjian-lm, qingjian-format, qingjian-neural and qingjian-render, with applications under apps/cli, apps/macos, apps/windows/server, apps/windows/tsf and apps/windows/settings, plus tools/dict-convert and tools/gloss-gen. The README states the principle directly: the input engine is platform-agnostic and each platform only connects to the system input interface and the candidate window.

The platform mapping is documented as macOS to Input Method Kit, Windows to Text Services Framework, and Linux to IBus or Fcitx. Only the first two have code in the workspace. The Windows layout is worth noting because apps/windows/server and apps/windows/tsf are separate crates: the README describes the Windows build as a TSF text service plus an independent input engine process, so the engine is not loaded into the host application.

The dependency list hints at where the cost sits. Cargo.toml pins ferrous-opencc for conversion, jiff for date and time candidates in the local timezone, and foldhash for the frequency, language model and personal n-gram tables. The comment attached to foldhash explains the reason: the hot path hashes string keys tens of thousands of times per keystroke for abbreviated pinyin, where SipHash would cost tens of nanoseconds per lookup. The README also mentions a local small model that reranks candidates after a pause when a full pinyin sentence is typed in one go. That reranking is the part of the pipeline most likely to be felt as latency, and the README does not publish timing figures for it.

Installing Qingjian and typing a first sentence

The README does not contain build-from-source instructions. It points to qingjian.app/download for macOS and Windows packages and to qingjian.app/docs for installation, key bindings, settings, and data and privacy notes. The current release tags are macos-v0.1.2 and windows-v0.1.0-alpha.2, so the Windows build is explicitly at alpha stage while the macOS one is not.

If you are working from the repository instead, the workspace is a standard Cargo layout with a pinned toolchain. The apps/cli crate is the piece that lets you exercise the engine without installing a system input method, which is the fastest way to see candidate output before touching your OS input settings. The repository does not document a specific command for running it, so check apps/cli before assuming an invocation.

The environment file is optional. The .env.example comments state that every variable has a default and that a missing value does not raise an error, so copying it is a convenience rather than a requirement.

cp .env.example .env

To change what appears beside candidates, set the learning language. The example file lists en, ja and es, and RUST_LOG uses tracing-subscriber EnvFilter syntax if you need engine logs while testing.

QINGJIAN_LEARNING_LANGUAGE=ja
RUST_LOG=info,qingjian_core=debug
QINGJIAN_LOG_DIR=logs

According to the README, after installing on macOS you type a full pinyin sentence without selecting candidates, pause, and the local model reranks the list while each candidate carries its gloss. What you should see is the candidate list with a smaller translation line under or beside the primary text, not a popup, not a quiz, and not a second language column.

Where Qingjian is the wrong tool, and what the README does not promise

The README's own Status section is the clearest limitation: it describes Qingjian as a test version, in personal use, being packaged for a small number of testers, and states that the API, project structure and feature design may all change substantially. Anyone evaluating it for a team rollout should read that as the governing statement. There is no documented stability guarantee, no migration path for settings between versions, and the README does not document rollback if an upgrade goes wrong.

Linux is the second boundary. The README lists IBus and Fcitx under the platform table, but the workspace members contain no Linux application crate. Treat Linux as a stated direction, not a supported target.

The single-language rule is a limitation if you wanted the opposite. If you are studying two languages at once, Qingjian will not help; you switch the learning language and lose the other. The README presents this as a deliberate refusal rather than a gap, and it is consistent with the project's list of things it will not do: no five or six languages in the candidate window, no test popping up every few words, no forced memorisation, no complex UI interfering with typing, and no sacrificing input efficiency for the learning feature.

The privacy section is unusually concrete for a project at this stage. The README states that pinyin conversion, the dictionary, learning and glosses all happen locally, with no account and no telemetry. Cloud suggestion is off by default; when enabled, requests go from the user's machine to an AI provider the user configures, not through the author. Input logs are written locally and can be turned off and cleared. The README does not describe what those logs contain, so if that matters to you, the data and logs page under qingjian.app/docs is the place to check before enabling anything.

How Qingjian differs from Rime and from a study app

The closest comparison is Rime, the long-standing open source input method engine. Both are offline, both let you own your configuration, and both are built by people who care about input behaviour rather than about shipping a consumer product. The difference is in what the engine is for. Rime is a general input engine whose schemas and dictionaries you assemble and tune yourself; its power comes from configurability, and its cost is that you configure it. Qingjian ships a fixed opinionated pipeline: pinyin in, candidates out, one gloss attached, one local model reranking after a pause.

The second comparison is a vocabulary app such as Anki. Anki schedules spaced repetition and expects you to sit down and review. Qingjian does the opposite: it removes the session entirely and puts the exposure inside an activity you were already doing. That is also its weakness. There is no scheduling, no retention tracking and no review queue, so nothing verifies that the glosses you saw were learned. If your goal is measurable vocabulary growth, a spaced-repetition tool is the better instrument, and Qingjian is not trying to be one.

A third reference point is the operating system's own input method. Those are more stable and better integrated, and they will not change their feature design under you. They also will not show a translation beside a candidate, which is the entire reason Qingjian exists.

Licence, bundled data and the cost of upgrading

The code is GPL-3.0-or-later. The README states that you may use, modify and redistribute it, and that modified distributions must be open sourced under the same terms. The name Qingjian and its logo are excluded from the licence grant, so a fork cannot ship under the same branding. Qingjian is free through official channels, and the README adds that if you paid someone to obtain it, you were cheated.

The data is a separate question from the code. Dictionaries, the language model, the gloss table, emoji, the English word list and vocabulary levels each follow the licence of their source. The README points to docs/design/landscape.md for the inventory and notes that the About page in preferences lists a copy as well. This matters more than it does for a typical application, because the glosses are the product: if you redistribute a build, the data licences govern what you can ship, and they are not uniform. This is a description of the licensing structure, not legal advice; check the inventory yourself before redistributing.

Upgrade cost is hard to assess from the repository. The workspace version is 0.1.1 while the release tags are macos-v0.1.2 and windows-v0.1.0-alpha.2, and there is a CHANGELOG.md at the top level. The README does not describe a settings migration path between versions, and given the Status section's warning that the project structure may change substantially, treating any configuration as portable across releases would be an assumption rather than a documented guarantee.

Editorial conclusion

Adopt Qingjian if you type Chinese on macOS or Windows and want passive vocabulary exposure without opening a study app, and if you accept that the README calls it a test build whose API and feature design may still change. Do not adopt it if you need a stable, documented Linux build (the README lists IBus/Fcitx only as a platform direction) or a finished product for non-technical users. Before installing, verify two things: whether the download page at qingjian.app/download currently offers a build for your OS, and whether the bundled data licences listed in docs/design/landscape.md are acceptable for how you intend to use and redistribute it.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. qingjian-team/qingjian on GitHub
4. README
5. Releases