How to Use Custom Prompts with Tokens in Read Frog: `[TARGET_LANG]`, `[INPUT]`, `[TITLE]`, and `[SUMMARY]`

Read Frog supports four placeholder tokens—[TARGET_LANG], [INPUT], [TITLE], and [SUMMARY]—that the runtime replaces with actual values like the target language code, source text, article title, and summary before sending requests to the LLM.

Read Frog is a browser extension that leverages large language models for contextual translation. Instead of locking users into rigid translation instructions, the tool exposes a custom prompt system built around four substitution tokens defined in src/utils/constants/prompt.ts. These tokens allow you to write reusable templates that adapt dynamically to each translation task while maintaining type safety through TypeScript constants.

Understanding the Four Core Tokens

The token system centers on four constants exported from src/utils/constants/prompt.ts:

export const TOKENS = ["targetLang", "input", "title", "summary"] as const;
export const TARGET_LANG = TOKENS[0];
export const INPUT = TOKENS[1];
export const TITLE = TOKENS[2];
export const SUMMARY = TOKENS[3];

At runtime, these map to double-brace placeholders via the getTokenCellText helper:

export const getTokenCellText = (token: string) => `{{${token}}}`;

Thus, while the documentation refers to tokens like [TARGET_LANG], the actual strings injected into prompt templates appear as {{targetLang}}, {{input}}, {{title}}, and {{summary}}.

Each token serves a specific purpose in the translation pipeline:

• {{targetLang}} – The ISO language code (e.g., ja, es) indicating the desired output language.
• {{input}} – The raw text or subtitle fragment requiring translation.
• {{title}} – The article's headline, providing the model with document-level context.
• {{summary}} – A brief overview of the article content, further grounding the translation in context.

Default Prompt Templates

Read Frog ships with built-in system and user prompts that demonstrate token usage. Both reside in src/utils/constants/prompt.ts.

The system prompt establishes the translator's role and injects metadata:

export const DEFAULT_TRANSLATE_SYSTEM_PROMPT = `You are a professional ${getTokenCellText(TARGET_LANG)} native translator who needs to fluently translate text into ${getTokenCellText(TARGET_LANG)}.

## Translation Rules

1. Output only the translated content …

## Document Metadata for Context Awareness

Title: ${getTokenCellText(TITLE)}
Summary: ${getTokenCellText(SUMMARY)}`;

The user prompt focuses on the translation request itself:

export const DEFAULT_TRANSLATE_PROMPT = `Translate to ${getTokenCellText(TARGET_LANG)}:

${getTokenCellText(INPUT)}`;

These templates ensure the LLM receives consistent formatting while remaining adaptable to different languages and content types.

Runtime Token Substitution

When you initiate a translation, Read Frog executes the replacement logic in src/utils/prompts/translate.ts. The replaceTokens function performs a straightforward string substitution for both custom and default prompts:

const replaceTokens = (text: string) =>
  text
    .replaceAll(getTokenCellText(TARGET_LANG), targetLang)
    .replaceAll(getTokenCellText(INPUT), input)
    .replaceAll(getTokenCellText(TITLE), title)
    .replaceAll(getTokenCellText(SUMMARY), summary);

The getTranslatePrompt function (and its subtitle counterpart in src/utils/prompts/subtitles.ts) gathers runtime values—targetLang from the UI selection, input from the selected text, and title/summary from options?.content—then feeds them through replaceTokens before dispatching the request to your configured LLM provider.

Creating Custom Prompts

You can override the defaults through the extension's settings panel under Translate → Custom Prompts. The configuration persists as customPromptsConfig inside DEFAULT_TRANSLATE_PROMPTS_CONFIG (defined in src/utils/constants/config.ts).

A valid custom prompt JSON object uses the same four tokens:

{
  "id": "expert-academic-prompt",
  "systemPrompt": "You are an expert {{targetLang}} academic translator. Maintain formal tone. Reference: Title: {{title}} | Summary: {{summary}}",
  "prompt": "Translate the following academic text into {{targetLang}}:\n\n{{input}}"
}

When selected, getTranslatePrompt loads your custom strings and processes them through the identical replaceTokens pipeline, ensuring backward compatibility with the token contract.

Example Usage in Code

To programmatically retrieve a populated prompt:

const { systemPrompt, prompt } = await getTranslatePrompt(
  "de",                                    // targetLang
  "Machine learning transforms education.", // input
  { 
    content: { 
      title: "AI in Education", 
      summary: "Exploring ML impact on learning" 
    } 
  }
);

After substitution, systemPrompt contains the German-specific instructions and metadata, while prompt holds the final user message with the actual text to translate.

Summary

• Four tokens form the backbone of Read Frog's prompt system: {{targetLang}}, {{input}}, {{title}}, and {{summary}}, defined in src/utils/constants/prompt.ts.
• Double-brace syntax ({{token}}) is the literal format used in template strings, generated by getTokenCellText.
• Runtime replacement occurs in src/utils/prompts/translate.ts via the replaceTokens function, which substitutes placeholders with live data before LLM transmission.
• Custom prompts are stored in customPromptsConfig and processed through the same pipeline, allowing power users to tailor LLM behavior without forking the codebase.

Frequently Asked Questions

What happens if I omit a token from my custom prompt?

Omitting tokens like {{title}} or {{summary}} simply means that context won't appear in the LLM request. The replaceTokens function only substitutes existing matches, so the prompt remains valid but lacks that specific metadata. You must include {{input}} and {{targetLang}} for functional translation, though the system won't enforce this programmatically.

Can I create new tokens beyond the four standard ones?

No. The token list is hard-coded as a const array in src/utils/constants/prompt.ts. The replaceTokens function explicitly handles only targetLang, input, title, and summary. Adding custom tokens would require modifying the source code and rebuilding the extension.

Where does Read Frog store my custom prompt configurations?

Custom prompts persist in the extension's global configuration object (DEFAULT_TRANSLATE_PROMPTS_CONFIG) within the customPromptsConfig field, managed through src/utils/constants/config.ts. This storage is local to your browser extension instance and syncs according to your browser's extension storage policies.

Do subtitle translations use the same token system?

Yes. The getSubtitlesTranslatePrompt function in src/utils/prompts/subtitles.ts imports and reuses the identical replaceTokens logic and token constants from prompt.ts. Whether translating article text or video subtitles, the four-token contract remains consistent.

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