Recommended Directory Structure for Integrating RIME Grammar (.gram) Files: Complete Setup Guide

Place the wanxiang-lts-zh-hans.gram file in your RIME user directory alongside your schema YAML files and enable the octagram module with the correct language identifier in your schema configuration.

The amzxyz/rime-lmdg repository provides a high-quality n-gram language model for RIME input methods. Understanding the recommended directory structure for integrating this RIME grammar file ensures the octagram module correctly loads the statistical model for enhanced input prediction.

Understanding the RIME Grammar Model Architecture

The Generated .gram File

According to the source code in 语法模型构建.py (lines 293-304), the build process generates a file named wanxiang-lts-zh-hans.gram. This binary grammar model contains the n-gram statistics that power contextual suggestions. The wanxiang-tools.py file (line 89) defines this filename as a constant: MODEL_FILE = "wanxiang-lts-zh-hans.gram", ensuring consistency across the toolchain.

Directory Placement Requirements

RIME requires the .gram file to reside in the user directory at the same level as your schema definition files (*.yaml). The engine loads grammar models by resolving the language parameter in the octagram configuration against files in this directory. Unlike dictionary files that might live in subdirectories, grammar models must sit at the root of the user configuration folder.

Step-by-Step Integration Guide

1. Obtain the Grammar Model

You have two primary methods to acquire the .gram file according to the repository source:

Option A: Download Pre-built Release

Use scripts/fetch_any_dict.py (lines 800-801) to automatically download the latest release:

from pathlib import Path
from scripts.fetch_any_dict import download_dict

rime_dir = Path.home() / ".config" / "ibus" / "rime"
download_dict(
    url_dict=None,
    out_url_directory=rime_dir,
    is_download_gram=True  # Target only the .gram file

)

Option B: Build from Source

Run the generation script to create the grammar model locally:

python 语法模型构建.py

This executes the build logic defined at lines 293-304 of 语法模型构建.py, producing wanxiang-lts-zh-hans.gram in your current working directory.

2. Position the File in RIME User Directory

Move or copy the generated/downloaded file to your platform-specific RIME user directory:

• Windows: %APPDATA%\Rime\ (typically C:\Users\<Username>\AppData\Roaming\Rime\)
• macOS: ~/Library/Rime/ or ~/.config/ibus/rime/ depending on frontend
• Linux: ~/.config/ibus/rime/ or ~/.local/share/fcitx5/rime/

The file must sit at the root level alongside your default.custom.yaml and schema files:

~/.config/ibus/rime/
├── wanxiang-lts-zh-hans.gram    # Grammar model (root level)

├── wanxiang.schema.yaml         # Schema definition

└── default.custom.yaml          # Custom configuration

3. Enable Octagram in Schema Configuration

In your schema YAML file (e.g., wanxiang.schema.yaml), include the octagram module and specify the language identifier matching your .gram filename (minus the extension):

__include: octagram   # Enable grammar model support

octagram:
  __patch:
    grammar:
      language: wanxiang-lts-zh-hans  # Matches .gram filename without extension

      collocation_max_length: 7
      collocation_min_length: 2
      collocation_penalty: -10
      non_collocation_penalty: -20
      weak_collocation_penalty: -35
      rear_penalty: -12
    translator/contextual_suggestions: false
    translator/max_homophones: 5
    translator/max_homographs: 5

Automated Deployment with sync_rime.py

For users maintaining multiple installations, the repository provides scripts/sync_rime.py, which automates the download and placement process:

python scripts/sync_rime.py

This script handles the directory detection and file placement automatically, ensuring the wanxiang-lts-zh-hans.gram file lands in the correct location regardless of your operating system.

Critical Compatibility Considerations

According to the project README.md, do not enable both octagram and cloud plugins simultaneously. RIME frontends like Weasel (Windows) or Squirrel (macOS) cannot load both modules concurrently. Choose either the local grammar model via octagram or the cloud prediction service, but never both, or the grammar model will fail to initialize.

Summary

• Obtain the wanxiang-lts-zh-hans.gram file via fetch_any_dict.py or 语法模型构建.py
• Place the file in your RIME user directory root (same level as schema YAMLs)
• Configure __include: octagram in your schema with language: wanxiang-lts-zh-hans
• Avoid using cloud plugins concurrently with octagram
• Restart your input method to load the grammar model into memory

Frequently Asked Questions

Where exactly do I place the .gram file on Windows?

Place wanxiang-lts-zh-hans.gram directly in %APPDATA%\Rime\ (resolve to C:\Users\<YourName>\AppData\Roaming\Rime\). The file must sit at the root of this directory, not inside subfolders like build/ or luna_pinyin.userdb/, for RIME to resolve the grammar reference.

Can I rename the .gram file to something else?

While technically possible if you modify wanxiang-tools.py (line 89), it is not recommended. The octagram configuration uses the language parameter to construct the filename lookup. If you rename the file, you must update the language: value in your schema YAML to match exactly (without the .gram extension).

Why is my grammar model not loading after placement?

First, verify the file is in the correct directory (same level as your active schema). Second, confirm you have included __include: octagram in your schema YAML and that the language: parameter matches the filename. Finally, ensure you are not running a cloud plugin simultaneously, as noted in the README.md, which prevents octagram initialization.

How do I verify the grammar model is active during typing?

After deployment and restarting RIME, type phrases that require contextual disambiguation. With collocation_max_length set in your octagram configuration (as shown in lines 293-304 of the build script documentation), you should observe improved prediction for multi-character collocations. Check your RIME log files if suggestions fail to appear, as they will report grammar loading errors.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}