# How New Words Are Added to the Dictionary Files in HalleluJAH-Im

> Learn how to add new words to HalleluJAH-Im's dictionary files. Discover the manual update process and the add_new_words.js utility for efficient regeneration.

- Repository: [dongyuwei/hallelujahim](https://github.com/dongyuwei/hallelujahim)
- Tags: how-to-guide
- Published: 2026-02-28

---

**New words are added by updating the source frequency file [`google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/google_227800_words.json) manually or via the [`util/add_new_words.js`](https://github.com/dongyuwei/hallelujahim/blob/main/util/add_new_words.js) utility, then regenerating the final [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json) dictionary using the Node.js merge script.**

The `dongyuwei/hallelujahim` repository maintains a structured English-Chinese dictionary centered on the file [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json). Understanding how to add new words to this dictionary requires navigating a build pipeline that merges word frequency data with optional Chinese translations rather than editing the final JSON directly.

## Understanding the Dictionary Architecture

The [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json) file is a generated artifact, not a source file. It is produced by merging two distinct data sources:

1. **[`dictionary/google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/google_227800_words.json)** – The canonical frequency map containing English words paired with usage counts (e.g., `"hello": 12345`). This file serves as the authoritative list of which words exist in the dictionary.
2. **[`dictionary/transformed_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/transformed_translation.json)** – A static mapping of Chinese translations for a subset of words, derived from the CEDICT dataset.

The generation logic resides in [`dictionary/words_with_frequency_and_translation.js`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/words_with_frequency_and_translation.js). This script iterates over every entry in the frequency map, copies the frequency value, and conditionally appends a `translation` field when a matching key exists in the translation source.

```javascript
var data = {};
for (let key in words) {
    data[key] = { frequency: words[key] };
    if (translation[key]) {
        data[key].translation = translation[key];
    }
}
fs.writeFileSync('./words_with_frequency_and_translation.json',
                 JSON.stringify(data), 'utf-8');

```

## How to Add New Words to the Dictionary

Adding vocabulary requires a two-phase process: updating the source frequency data and rebuilding the output file.

### Step 1 – Update the Frequency Source

Modify [`dictionary/google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/google_227800_words.json) using one of the following methods:

**Manual Editing:**
Directly manipulate the JSON structure to insert new entries or adjust existing frequency counts:

```json
{
    "neighbourhood": 124567,
    "hello": 987654321
}

```

**Programmatic Addition:**
Use the provided utility script [`util/add_new_words.js`](https://github.com/dongyuwei/hallelujahim/blob/main/util/add_new_words.js) to automate modifications. This script demonstrates how to read the JSON, apply changes, and persist updates:

```javascript
var fs = require('fs');
var words = JSON.parse(fs.readFileSync('../dictionary/google_227800_words.json','utf-8'));

// Add new entry or increment existing frequency
words["neighbourhood"] = (words["neighbourhood"] || 0) + 1;

fs.writeFileSync('../dictionary/google_227800_words.json',
                 JSON.stringify(words), 'utf-8');

```

### Step 2 – Regenerate the Combined Dictionary

After updating the source frequency file, execute the merge script to produce the final dictionary:

```bash
node dictionary/words_with_frequency_and_translation.js

```

This command runs the generation logic that combines the frequency data from [`google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/google_227800_words.json) with available translations from [`transformed_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/transformed_translation.json), outputting the updated [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json).

### Optional Step – Add IPA Phonetics

For phonetic transcription support, run the Python helper script after generating the base dictionary:

```bash
python3 dictionary/words_with_frequency_and_translation_and_ipa.py

```

This script reads the freshly generated JSON, adds an `"ipa"` field using the `eng_to_ipa` library, and writes [`words_with_frequency_and_translation_and_ipa.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation_and_ipa.json) for applications requiring pronunciation data.

## Key Files in the Dictionary Pipeline

| File | Purpose |
|------|---------|
| [`util/add_new_words.js`](https://github.com/dongyuwei/hallelujahim/blob/main/util/add_new_words.js) | Utility for programmatically updating word frequencies without manual JSON editing. |
| [`dictionary/google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/google_227800_words.json) | Source of truth for English vocabulary and frequency counts. |
| [`dictionary/transformed_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/transformed_translation.json) | Static Chinese translation data derived from CEDICT. |
| [`dictionary/words_with_frequency_and_translation.js`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/words_with_frequency_and_translation.js) | Node.js generator that merges frequency and translation sources. |
| [`dictionary/words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/words_with_frequency_and_translation.json) | Final output dictionary consumed by the application at runtime. |
| [`dictionary/words_with_frequency_and_translation_and_ipa.py`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/words_with_frequency_and_translation_and_ipa.py) | Optional Python script to append IPA phonetic symbols. |
| [`dictionary/words_with_frequency_and_translation_and_ipa.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/words_with_frequency_and_translation_and_ipa.json) | IPA-augmented dictionary variant. |

## Summary

- The [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json) file is **generated**, not hand-edited.
- New words are added by updating [`dictionary/google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/google_227800_words.json) manually or via [`util/add_new_words.js`](https://github.com/dongyuwei/hallelujahim/blob/main/util/add_new_words.js).
- Running `node dictionary/words_with_frequency_and_translation.js` merges frequency data with optional Chinese translations from [`transformed_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/transformed_translation.json).
- Optional IPA phonetics can be appended using [`dictionary/words_with_frequency_and_translation_and_ipa.py`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/words_with_frequency_and_translation_and_ipa.py).

## Frequently Asked Questions

### Can I edit [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json) directly?

No. Direct modifications to this file will be lost when the generation script runs. Always update the source frequency file [`google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/google_227800_words.json) and regenerate the dictionary using the Node.js merge script.

### How do I add a Chinese translation for a new word?

Translations are stored in [`dictionary/transformed_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/dictionary/transformed_translation.json). Add your word-translation pair to this static file, then rerun `node dictionary/words_with_frequency_and_translation.js`. If the word exists in both the frequency source and the translation source, the final JSON will include the `translation` field.

### What is the purpose of the [`add_new_words.js`](https://github.com/dongyuwei/hallelujahim/blob/main/add_new_words.js) utility?

This script provides a programmatic interface for batch-updating word frequencies in [`google_227800_words.json`](https://github.com/dongyuwei/hallelujahim/blob/main/google_227800_words.json). It demonstrates how to read, modify, and write the JSON without manual editing, which is essential for automated pipelines or bulk vocabulary additions.

### Does adding a word require restarting the application?

Yes. The dictionary files are loaded into memory at application startup. After regenerating [`words_with_frequency_and_translation.json`](https://github.com/dongyuwei/hallelujahim/blob/main/words_with_frequency_and_translation.json) or the IPA-augmented variant, you must restart the application to load the updated vocabulary.