Custom Translation Prompts

Prompt Data Structure and Format#

Custom translation prompts are stored as objects with four fields: id (string, UUID), name (string), systemPrompt (string), and prompt (string). All custom prompts are managed in the translation configuration under customPromptsConfig, which includes a promptId field (the currently selected prompt ID, or null for the default prompt) and a patterns array (the list of all available custom prompts).

There are now two independent custom prompts configurations:

Webpage Translation Prompts: Managed under translate.customPromptsConfig in the configuration.
Video Subtitles Prompts: Managed under videoSubtitles.customPromptsConfig in the configuration.

Each section maintains its own selected prompt and list of custom prompts. The default prompt for each is not stored in configuration, but defined as a code constant and referenced in the UI using a sentinel value (__default__). When promptId is null, the system uses the default prompt for that section. Only custom prompts are persisted in the configuration.

Prompt templates support tokens such as {{targetLanguage}} and {{input}}, which are replaced at runtime with the actual target language and input text. Both systemPrompt and prompt fields support these tokens. For example:

{
  "name": "Formal Style",
  "systemPrompt": "You are a professional translator. Always use a formal tone.",
  "prompt": "Translate the following text to {{targetLanguage}} in a formal tone: {{input}}"
}

Note: These token names were renamed in configuration version 064 for improved clarity. Previously, {{targetLang}} was used instead of {{targetLanguage}}, {{title}} instead of {{webTitle}}, {{summary}} instead of {{webSummary}}, and {{context}} instead of {{paragraphs}}. Existing user configurations are automatically migrated to use the new token names.

The default prompt includes translation rules and uses the same token format, split between systemPrompt and prompt:

System Prompt:
You are a professional {{targetLanguage}} native translator who needs to fluently translate text into {{targetLanguage}}.

## Translation Rules
1. Output only the translated content, without explanations or additional content (such as "Here's the translation:" or "Translation as follows:")
2. The returned translation must maintain exactly the same number of paragraphs and format as the original text.
3. If the text contains HTML tags, consider where the tags should be placed in the translation while maintaining fluency.
4. For content that should not be translated (such as proper nouns, code, etc.), keep the original text.

## Document Metadata for Context Awareness
Webpage title: {{webTitle}}
Webpage summary: {{webSummary}}

Prompt:
Translate to {{targetLanguage}}:
{{input}}

Example configuration for webpage translation:

"customPromptsConfig": {
  "promptId": null, // null means default prompt
  "patterns": [
    {
      "id": "uuid-123",
      "name": "Technical Translation",
      "systemPrompt": "Translate with technical accuracy and preserve terminology.",
      "prompt": "Translate to {{targetLanguage}} with technical accuracy: {{input}}"
    }
  ]
}

Example configuration for video subtitles:

"videoSubtitles": {
  ...,
  "customPromptsConfig": {
    "promptId": null,
    "patterns": []
  }
}

Each section (webpage translation and video subtitles) uses its own prompt selection and list. Changes in one do not affect the other.

Creating, Editing, and Deleting Prompts (Options Page)#

On the options page, users manage custom prompts through dedicated UIs for both webpage translation and video subtitles. Each section ("Webpage Translation Prompts" and "Custom Subtitle Prompts") provides its own prompt management interface. Each custom prompt is displayed as a card showing its name and a truncated preview of the system prompt and prompt text. Users can add a new prompt or edit an existing custom prompt using a form that includes input fields for the prompt name, system prompt, and prompt text. The system prompt field is used to provide high-level translation instructions and rules, while the prompt field is used for the main translation request. Both text areas support quick insertion of tokens (e.g., {{input}}, {{targetLanguage}}) via buttons, with tooltips explaining each token.

Editing and deleting are disabled for the default prompt, which is shown as a view-only card. All fields must be filled before saving a custom prompt. Users can delete custom prompts using a confirmation dialog. After confirming deletion, the dialog closes automatically. If the deleted prompt was selected, the system resets to the default prompt (by setting promptId to null).

The workflow and UI for creating, editing, and deleting prompts are the same for both webpage translation and video subtitles, but the prompts are managed independently in each section.

Exporting and Importing Prompts#

Users can export custom prompts as a JSON file using the export feature on the options page. The export workflow supports multi-selection: users can enter "export mode" by clicking the export button in either the webpage translation or video subtitles prompts section, then select one or more custom prompts using checkboxes displayed on each prompt card. The default prompt is excluded from export selection and cannot be exported. After selecting prompts, clicking the "Export Selected" button downloads a JSON file containing the selected custom prompts. The exported file includes all prompt fields except for id (i.e., name, systemPrompt, and prompt). Export mode can be canceled at any time.

Export and import actions are independent for webpage translation and video subtitles. Exporting from one section only includes prompts from that section.

Example export file:

[
  {
    "name": "Conversational",
    "systemPrompt": "Translate as if speaking to a friend.",
    "prompt": "Translate to {{targetLanguage}} as if speaking to a friend: {{input}}"
  }
]

To import prompts, use the import button in the relevant section and select a .json file. Imported prompts are validated to ensure they have name, systemPrompt, and prompt fields; invalid files are rejected with user feedback. Each imported prompt receives a new unique ID and is merged into the existing configuration for that section. The default prompt cannot be imported or overwritten.

Prompt selection is visually represented as a radio group card interface on the options page, with separate sections for webpage translation and video subtitles. The currently active prompt in each section is highlighted and marked as "in use." Clicking a prompt card (outside of export mode) sets it as the active prompt for that section, which is saved in the configuration as promptId (or null for the default prompt) and used for subsequent translations of that type. Only one prompt can be active at a time per section. If the selected custom prompt is deleted, the system falls back to the default prompt (promptId: null).

In the popup page, users select the active prompt for webpage translation using a dropdown menu populated from the configured custom prompts, with the default prompt shown as a separate option. (Subtitle prompt selection is managed only in the options page.) The selected prompt ID is saved to the configuration and used for subsequent translations. If the selected prompt is not found, the system falls back to the default prompt.

Prompt selection for webpage translation and video subtitles is independent: changing the prompt in one section does not affect the other.

Usage Scenarios and Customization#

Custom prompts can be tailored for various translation needs, such as:

Formal or conversational tone
Technical accuracy for expert audiences
Language learning, e.g., including original terms in parentheses
Literary or creative translation styles
Subtitle-specific formatting or brevity requirements

For example, a prompt for language learners might be:

Translate the following text to {{targetLanguage}}. For each key term, include the original English in parentheses: {{input}}

For video subtitles, you might use a prompt like:

Translate the following subtitle to {{targetLanguage}}. Keep the translation concise and suitable for on-screen display: {{input}}

The prompt format is extensible. While only {{targetLanguage}} and {{input}} are currently supported, the system is designed to allow additional tokens in the future.

Webpage translation and video subtitles each use their own set of prompts, so you can tailor prompts for the specific needs of each translation type.

Internationalization#

All UI strings related to custom prompts are localized using the i18n system, ensuring that users can manage and select prompts in their preferred language. Tooltips, button labels, and export mode actions are also localized.

Extending Prompts#

To extend or customize prompts for different translation needs, create new prompt templates using the options page UI. Use the token buttons to insert placeholders, and provide clear instructions in the prompt text to guide the translation model. Export and share your prompts as JSON files, or import prompts created by others to expand your available translation styles.