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

New words are added by updating the source frequency file google_227800_words.json manually or via the util/add_new_words.js utility, then regenerating the final 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. 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 file is a generated artifact, not a source file. It is produced by merging two distinct data sources:

1. 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 – 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. 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.

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 using one of the following methods:

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

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

Programmatic Addition: Use the provided utility script util/add_new_words.js to automate modifications. This script demonstrates how to read the JSON, apply changes, and persist updates:

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:

node dictionary/words_with_frequency_and_translation.js

This command runs the generation logic that combines the frequency data from google_227800_words.json with available translations from transformed_translation.json, outputting the updated 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:

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 for applications requiring pronunciation data.

Key Files in the Dictionary Pipeline

File	Purpose
util/add_new_words.js	Utility for programmatically updating word frequencies without manual JSON editing.
dictionary/google_227800_words.json	Source of truth for English vocabulary and frequency counts.
dictionary/transformed_translation.json	Static Chinese translation data derived from CEDICT.
dictionary/words_with_frequency_and_translation.js	Node.js generator that merges frequency and translation sources.
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	Optional Python script to append IPA phonetic symbols.
dictionary/words_with_frequency_and_translation_and_ipa.json	IPA-augmented dictionary variant.

Summary

• The words_with_frequency_and_translation.json file is generated, not hand-edited.
• New words are added by updating dictionary/google_227800_words.json manually or via 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.
• Optional IPA phonetics can be appended using dictionary/words_with_frequency_and_translation_and_ipa.py.

Frequently Asked Questions

Can I edit 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 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. 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 utility?

This script provides a programmatic interface for batch-updating word frequencies in 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 or the IPA-augmented variant, you must restart the application to load the updated vocabulary.

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