Module Creation Tutorial

From zero to a working module in 3 steps.

---

Step 1: Generate with CLI

node packages/create-qt-module/index.js

Interactive prompt:

🧩  QuickTranslate Module Scaffold

Select module type:
  1. Translation Engine
  2. Interaction Mode
  ...

Number (1-6): 1
Module name: Echo Translator
Author: myname
Short description: Demo module for testing

Output: translator-echo-translator.qt-module

---

Step 2: Edit the Code

Open the generated .qt-module file, find translate() and implement your logic:

// Before
async translate(text, from, to) {
  throw new Error('translate() not implemented')
}

// After — DeepL API example
async translate(text, from, to) {
  const resp = await fetch('https://api.deepl.com/v2/translate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'DeepL-Auth-Key ' + apiKey
    },
    body: JSON.stringify({
      text: [text],
      source_lang: from.toUpperCase(),
      target_lang: to.toUpperCase()
    })
  })
  const data = await resp.json()
  return data.translations[0].text
}

---

Step 3: Import to QuickTranslate

1. Open QuickTranslate → click 🧩 Modules

2. Click 📥 Import Module

3. Select your .qt-module file

4. Confirm → Module appears in the list, toggle ON

---

Quick Test

Use the existing demo module:

echo-translator.qt-module

After importing, it prepends a prefix to translated text. You can change the prefix in ⚙️ settings.

---

Debugging

Import fails

Check manifest is complete:

Field	Type	Description
id	string	Lowercase alphanumeric with hyphens: engine-mymod
name	string	Use English name
version	string	x.y.z format
type	string	translator / mode / renderer / processor / service / theme

Translation not working

Ensure module toggle is ON

Check onActivate subscribes to translate:text

Check target filter: if (req.target && req.target !== 'engine-xxx') return

Check API endpoint accessibility and API Key

Settings not saving

options field key must match the key used in translate()

Config is stored at moduleSettings.{moduleId}

---

Reference Examples

echo-translator.qt-module — Minimal translator with options

modules/translator-google.js — Built-in Google Translate module

modules/translator-custom.js — Custom LLM module

modules/mode-quick-panel.js — Interaction mode example

---

Publishing

Follow STORE_GUIDE.md to submit your module to the QuickTranslate Module Store.