Pinyin-to-English Input Conversion: How HallelujahIM Maps "suanfa" to "algorithm"

HallelujahIM converts pinyin strings like "suanfa" into English words such as "algorithm" by looking up the input in a pre-built dictionary (cedict.json) and appending the associated English translations to the candidate list.

HallelujahIM is an open-source input method editor (IME) for macOS that supports pinyin-to-English input conversion, enabling users to type romanized Chinese phonetics and receive English vocabulary suggestions. This functionality bridges the gap between Chinese typing habits and English word retrieval by leveraging a static dictionary mapping that ships with the application.

Architecture of the Pinyin Lookup System

The conversion engine follows a straightforward dictionary lookup pattern that executes after normal Chinese word generation completes.

Loading the Dictionary at Startup

In src/ConversionEngine.mm, the ConversionEngine class initializes its pinyin dictionary during the -getPinyinData method call (lines 51-54). This method reads dictionary/cedict.json into the pinyinDict property, creating an in-memory mapping of pinyin strings to arrays containing both Chinese phrases and their English equivalents.

Normalizing User Input

When a user types into the input buffer, the engine first normalizes the string by converting it to lowercase. In src/ConversionEngine.mm (lines 82-84), the code stores the lowercased version of the raw input in the buffer variable to ensure case-insensitive dictionary lookups.

Generating and Merging Candidates

The candidate generation process occurs in three distinct phases within the -getCandidates: method (lines 91-112):

1. Standard candidate generation — The engine first produces Chinese word candidates using a Trie search and spelling-checker suggestions.
2. Pinyin dictionary lookup — The engine checks self.pinyinDict[buffer]. If the pinyin key exists, the entire array stored for that key is appended to the result list.
3. Deduplication and ordering — The combined list is trimmed to a maximum of 50 entries, the raw buffer is preserved as the first element, and duplicates are removed while maintaining the original order.

The cedict.json Dictionary Structure

The conversion relies on dictionary/cedict.json, which stores entries as key-value pairs where the key is a pinyin string and the value is an array of translations. For example, the entry for "suanfa" contains both the Chinese term and multiple English definitions:

"suanfa": [
   "算法",
   "arithmetic",
   "algorithm",
   "method of calculation"
]

When the user types "suanfa", the engine retrieves this array in src/ConversionEngine.mm (lines 99-102) and injects the English strings into the candidate window. This allows the user to select "algorithm" or "arithmetic" directly without typing the English letters.

Reproducing the Conversion in Objective-C

To reproduce the conversion programmatically, you can query the shared ConversionEngine instance directly. Note that the engine loads dictionary data asynchronously, so results populate after initialization completes.

// Access the shared conversion engine (dictionaries load in background)
ConversionEngine *engine = [ConversionEngine sharedEngine];

// Query candidates for the pinyin string "suanfa"
NSArray *candidates = [engine getCandidates:@"suanfa"];

// Output includes the raw buffer followed by English translations
NSLog(@"Candidates: %@", candidates);

Typical console output after the background loading finishes:

Candidates: (
    suanfa,
    algorithm,
    arithmetic,
    method of calculation,
    算法
)

Summary

• Dictionary-driven lookup: The pinyin-to-English input conversion uses dictionary/cedict.json, loaded into pinyinDict via -getPinyinData in src/ConversionEngine.mm.
• Case normalization: Input strings are lowercased before lookup to ensure "Suanfa" and "suanfa" return identical results.
• Merged candidate lists: English translations append to standard Chinese candidates, with deduplication and a 50-entry limit enforced in the engine.
• Direct API access: The getCandidates: method in ConversionEngine returns an NSArray containing the raw input followed by dictionary matches.

Frequently Asked Questions

What dictionary format does HallelujahIM use for pinyin-to-English conversion?

HallelujahIM uses a JSON file located at dictionary/cedict.json. Each key represents a pinyin string, and the corresponding value is an array containing the Chinese characters followed by English translations. The engine parses this file at startup and stores it in the pinyinDict property of ConversionEngine.

How does the engine handle mixed-case pinyin input?

The engine normalizes all input to lowercase before performing the dictionary lookup. In src/ConversionEngine.mm, the code explicitly converts the input buffer using lowercaseString (lines 82-84), ensuring that "Suanfa", "SUANFA", and "suanfa" all match the same dictionary entry.

Why do I see both Chinese characters and English words in the candidate list?

The cedict.json entries include both the Chinese phrase and its English definitions in a single array. When the engine retrieves a match for a pinyin string, it appends the entire array to the candidate list. This design allows users to select either the Chinese term or the English translation depending on their current input needs.

Is there a limit to how many candidates HallelujahIM displays?

Yes. The engine enforces a maximum of 50 candidates per query. After merging the standard Chinese word candidates with the pinyin dictionary results, the code trims the list to 50 entries while preserving the raw input buffer as the first element and removing duplicates without reordering the remaining items.

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