Chinese Comprehensible Input

Chinese Comprehensible Input — Obsidian Plugin

Turn any Chinese note in Obsidian into a learner-friendly comprehensible-input reading environment. Dictionary-aware tokenization, exposure tracking, SRS, and optional OpenAI-compatible AI story generation. Works on desktop and mobile (no Node/Electron at runtime).

Why This Plugin Exists

Learning a language should be enjoyable. Unfortunately, many learners experience the opposite: endless flashcards, grammar drills, vocabulary lists, and a constant feeling that progress is slow and difficult.

When I started learning Chinese, the biggest breakthrough was discovering Comprehensible Input.

The core idea is simple: instead of memorizing isolated words and grammar rules, you learn by consuming content that is just slightly above your current level. You acquire the language naturally through reading and listening, much like children learn their native language.

Tools such as DuChinese have shown how powerful this approach can be. Reading stories designed for your level is far more engaging than spending hours reviewing flashcards. For a long time, comprehensible input allowed me to progress while enjoying the process.

However, as your Chinese improves, a new problem appears.

At beginner and intermediate levels, common vocabulary appears frequently enough that repeated exposure naturally reinforces it. But as you advance, you start learning increasingly rare words. These words may only appear occasionally, making it difficult to retain them through reading alone. This is the point where many learners feel forced to return to flashcards and traditional spaced repetition systems.

The problem is that flashcards often break the flow and enjoyment of language learning. Instead of reading interesting content, you end up reviewing isolated vocabulary items again.

This plugin explores a different approach.

Spaced Repetition Through Stories

Instead of using flashcards, this plugin uses stories and meaningful content as the vehicle for spaced repetition.

With the help of AI, it becomes possible to generate or adapt content that naturally includes the vocabulary you need to review. Rather than seeing a word on a card, you encounter it inside a story, dialogue, article, or topic that interests you.

The goal is to combine the effectiveness of spaced repetition with the enjoyment of comprehensible input.

You can import Chinese texts that interest you, track your vocabulary knowledge, and receive content tailored to the words that need reinforcement. Learning becomes less about reviewing cards and more about reading Chinese every day.

A Better Reading Experience

Many Chinese reading tools provide pinyin and translations for every word. While helpful at first, this creates another problem: learners naturally rely on the easiest information available.

If English translations are always visible, your eyes drift toward English. If pinyin is always displayed, you start reading pinyin instead of recognizing characters.

As a result, character recognition develops more slowly than it should.

This plugin takes a different approach.

Words can be marked as:

• Known
• Partially known
• Unknown

Based on that knowledge, the plugin can selectively display characters, pinyin, or translations only where they are actually needed.

Words you already know remain visible as Chinese characters only, encouraging character recognition and reading fluency. Support is shown only for vocabulary that still requires assistance.

The result is a reading experience that provides help when necessary without constantly encouraging dependence on pinyin or translations.

Measure Real Progress

Another important aspect of language learning is feedback.

Many learners have only a vague sense of their progress. They know they have studied for months or years, but they cannot easily quantify what they have learned.

By tracking vocabulary knowledge over time, this plugin provides measurable insights into your progress:

• How many words you know
• Which words are improving
• Which words are being forgotten
• Whether your vocabulary is growing over time

Seeing tangible progress can be highly motivating, especially during the long journey of learning Chinese. The goal is not only to make learning more effective, but also to help learners stay motivated by making their improvement visible.

The Vision

The long-term vision of this project is simple:

Make Chinese learning feel more like reading and less like studying.

By combining comprehensible input, AI-generated content, vocabulary tracking, and story-based spaced repetition, this plugin aims to make language acquisition both effective and enjoyable—even beyond the intermediate stages where traditional comprehensible-input tools begin to struggle.

See NOTICE.md for license notes (CC-CEDICT, HSK).

Install

The plugin is not in the official Obsidian community-plugin store yet. Install via BRAT (recommended) or manually — full step-by-step guide in docs/install.md.

Documentation

Detailed guides live in docs/. Each settings section also links to the relevant page from inside Obsidian. Highlights:

• Install (BRAT or manual) — get the plugin into your vault
• FAQ — top issues and where the fix is
• OpenAI setup, privacy, and cost
• Ollama tips: model choice and getting good output
• Story generation, end to end
• Display modes & colors
• Word states (new / partial / known / unknown / ignored)
• Exposure tracking
• Spaced repetition
• Vault-mirror sync (for users who don't sync .obsidian/)
• Conflict resolution between devices

Limitations

• Mobile + Ollama needs a reachable LAN/Tailscale host (localhost from the phone points at the phone). See Ollama tips.
• OpenAI mode sends prompt + target words to OpenAI's servers — fine for most users, see the privacy section.
• The bundled seed dictionary is tiny; real use needs CC-CEDICT (see Data below).

Dev

npm install
npm run dev        # watch build
npm run build      # type-check + production bundle
npm test           # vitest
npm run test:cov   # coverage report + threshold enforcement
npm run check-release

GitHub Actions runs the same validation set on every PR and on pushes to main: build, tests, coverage, and the release guard. Actual BRAT publishing stays manual so the tagged release assets and notes are reviewed before going live.

Development policy:

• Use a dedicated branch for each bugfix, feature, or release-prep change. Preferred prefixes: fix/, feat/, release/.
• Merge changes to main through PRs after CI passes.
• External PRs must be approved by the maintainer before merge.

To install the dev build into a vault:

1. Build: npm run build.
2. Copy manifest.json, main.js, styles.css into <vault>/.obsidian/plugins/chinese-comprehensible-input/.
3. Enable in Obsidian → Community plugins.

Data

A tiny seed dictionary is bundled for development. For real use, drop a CC-CEDICT shard at <vault>/.cci-dictionary.json (array of {simplified, traditional, pinyin, definitions, hsk?}). See NOTICE.md for license notes.

Privacy

• No data leaves the device unless you configure an AI provider.
• In OpenAI-compatible mode, story generation may send prompt text and target words to the provider you configured.
• API keys are stored locally in Obsidian local storage and are not written to synced vault files.

Data storage

• Settings, vocabulary state, SRS state, and exposure history are stored in the plugin's local Obsidian data blob.
• If you enable the optional sync mirror, sanitized settings and vocabulary data are also written to JSON files inside your vault. API keys stay local.
• The bundled dictionary is only a small seed set. Normal use expects a user-supplied CC-CEDICT shard at <vault>/.cci-dictionary.json.