# Understanding the auto_phrase Feature for User Phrases in RIME Wanxiang

> Discover RIME Wanxiang's auto_phrase feature. It automatically adds user phrases to your dictionaries improving your typing experience without manual commands.

- Repository: [amzxyz/rime_wanxiang](https://github.com/amzxyz/rime_wanxiang)
- Tags: deep-dive
- Published: 2026-02-24

---

**The `auto_phrase` feature automatically records confirmed Chinese and English text into user dictionaries without manual "add-word" commands, leveraging the [`lua/auto_phrase.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lua/auto_phrase.lua) pipeline to build personalized vocabularies on-the-fly.**

The `auto_phrase` feature is an automatic phrase creation mechanism implemented in the amzxyz/rime_wanxiang input method schema. It captures committed text at runtime and persists it to user-specific dictionaries, eliminating manual editing while adapting the input experience to individual typing patterns through two complementary pipelines.

## How auto_phrase Works

The implementation distinguishes between **Chinese** and **English** input through separate validation logic in [`lua/auto_phrase.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lua/auto_phrase.lua). Both pipelines trigger when you confirm a candidate (typically by pressing **Space** or **Enter**), but they differ in their conditions and storage targets.

### Chinese auto_phrase Pipeline

When committing Chinese text, the feature activates only when three configuration switches and content validations pass simultaneously. According to the source in [`lua/auto_phrase.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lua/auto_phrase.lua), the `AP.commit_handler` function checks:

- `add_user_dict/enable_auto_phrase` is set to `true`
- `add_user_dict/enable_user_dict` is set to `true`
- The commit text contains **only Chinese characters** (validated via `AP.is_chinese_only` using Unicode range checks)
- All segments have selected candidates carrying **non-empty comments** (auxiliary codes)

If these conditions pass, the handler collects auxiliary codes from the comment cache, assembles a `custom_code` string, and calls `Memory:update_userdict` to insert a `DictEntry` into the `add_user_dict` user dictionary.

### English auto_phrase Pipeline

English auto_phrase operates under different constraints. The `wanxiang_english` user dictionary remains active regardless of the `enable_user_dict` setting. The trigger conditions in `AP.commit_handler` require:

- Raw input ending with a backslash (`\`)
- Commit text qualifying as an ASCII word (detected by `is_ascii_word`)

When triggered, the system stores the commit text together with the code derived from the raw input (excluding trailing backslashes) into `wanxiang_english`. It also creates a lowercase variant to ensure case-insensitive matching.

## Configuration and Setup

Enable the feature through your custom configuration file. The schema declares the switches in [`wanxiang.schema.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/wanxiang.schema.yaml), but you typically activate them in [`custom/wanxiang.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom/wanxiang.custom.yaml) or [`custom/wanxiang_pro.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom/wanxiang_pro.custom.yaml):

```yaml
add_user_dict/enable_user_dict: true
add_user_dict/enable_auto_phrase: true

```

The first switch activates the generic user dictionary infrastructure required for Chinese auto_phrase, while the second specifically enables the automatic phrase creation logic.

## Core Implementation Details

The [`lua/auto_phrase.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lua/auto_phrase.lua) file contains three critical components that orchestrate the feature.

### The Comment Cache Mechanism

During input processing, the `AP.func` iterator populates a `comment_cache` table mapping candidate text to auxiliary code comments. This cache is essential for Chinese auto_phrase because the comments supply the encoding information needed to construct the `custom_code` field:

```lua
-- Simplified illustration from lua/auto_phrase.lua
local comment_cache = {}
-- During iteration:
comment_cache[candidate.text] = candidate.comment

```

### Commit Handler Logic

The `AP.commit_handler` serves as the central dispatcher registered in `AP.init` as both a commit and delete notifier. It validates the input context, determines which pipeline to execute, constructs the `DictEntry` object, and persists it via `env.memory:update_userdict(entry, 1, "")`.

Helper functions support this logic:
- `AP.is_chinese_only(str)`: Validates that input contains only Chinese Unicode characters
- `is_ascii_word(str)`: Detects pure ASCII words for English validation

## Practical Usage Examples

### Adding Chinese Phrases

Type the phrase "万象方案" and select the candidate. If auxiliary codes appear in the comments (e.g., "wj", "xx", "fa"), pressing **Space** triggers the handler to build the code `"wj xx fa ..."` and write the entry `万象方案 1 wj xx fa ...` into `add_user_dict`. Subsequent typing of the same phrase retrieves it directly from your user dictionary.

### Adding English Words

Type `hello\` (including the trailing backslash) and press **Space**. The system detects the backslash suffix and ASCII content, storing both `hello` and `HELLO` entries in `wanxiang_english` with the code `hello`. Future typing of "hello" will prioritize this user-defined entry.

### Programmatic Entry Creation

While normally handled automatically, the underlying API usage follows this pattern from [`lua/auto_phrase.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lua/auto_phrase.lua):

```lua
local Memory = require('librime').Memory
local env = {engine = rime_engine}
env.memory = Memory(rime_engine, rime_engine.schema, "add_user_dict")

local entry = DictEntry()
entry.text = "万象"
entry.weight = 1
entry.custom_code = "wx "  -- Assembled from comment cache
env.memory:update_userdict(entry, 1, "")

```

## Summary

- **auto_phrase** provides automatic user dictionary population without manual add-word commands in amzxyz/rime_wanxiang.
- **Chinese pipeline** requires `enable_auto_phrase`, `enable_user_dict`, pure Chinese content, and auxiliary code comments to build entries in `add_user_dict`.
- **English pipeline** activates on trailing backslash (`\`) input, storing ASCII words in `wanxiang_english` with case-insensitive variants.
- **Core logic** resides in [`lua/auto_phrase.lua`](https://github.com/amzxyz/rime_wanxiang/blob/main/lua/auto_phrase.lua), utilizing `AP.commit_handler`, `comment_cache`, and `Memory:update_userdict` for persistence.
- **Configuration** occurs via `add_user_dict/enable_auto_phrase` and `add_user_dict/enable_user_dict` in custom YAML files.

## Frequently Asked Questions

### How do I enable the auto_phrase feature?

Set `add_user_dict/enable_user_dict: true` and `add_user_dict/enable_auto_phrase: true` in your [`custom/wanxiang.custom.yaml`](https://github.com/amzxyz/rime_wanxiang/blob/main/custom/wanxiang.custom.yaml) file. Both switches must be active for Chinese auto_phrase to function, while English auto_phrase only requires the user dictionary infrastructure to be present.

### Why isn't my Chinese phrase being saved to the user dictionary?

Verify that the commit text contains only Chinese characters (validated by `AP.is_chinese_only`), all segments have selected candidates with non-empty comments (auxiliary codes), and both configuration switches are enabled. The feature explicitly skips entries lacking auxiliary encoding information.

### What is the difference between the Chinese and English auto_phrase pipelines?

The Chinese pipeline requires explicit enabling via `enable_auto_phrase`, validates Unicode Chinese content, and stores entries in `add_user_dict` using assembled auxiliary codes. The English pipeline triggers automatically on backslash-terminated input, requires ASCII word content, and persists to `wanxiang_english` regardless of the auto_phrase toggle.

### Where are auto_phrase entries physically stored?

Chinese entries write to the `add_user_dict` user dictionary file, while English entries populate `wanxiang_english`. Both are standard RIME dictionary files that persist across sessions and can be backed up or version-controlled like other RIME configuration files.