Configuration & Getting Started

Follow these steps to configure the application. These settings are accessible via the File menu.

1. OpenAI Settings

Go to File → OpenAI settings to configure your connection to OpenAI. It is possible to use either direct OpenAI hosting or OpenAI models on Azure (both for completions and for embedding).

  • OpenAI API Key: Enter and save your OpenAI API Key (Required for direct OpenAI usage).
  • Embedding Model: Define the model for analyzing reference files (e.g., text-embedding-3-large).
  • Use Azure OpenAI instead:
    • When ticked, you must specify the Azure API Key, Completions Endpoint, Embedding Endpoint, and Azure Embedding API Key for your deployed models.
    • All other settings (like batch size and max concurrent requests) apply regardless of the host.
  • Performance Settings:
    • Embedding Batch Size: Segments sent in a single embedding request.
    • Max Concurrent Requests: Limit parallel requests to avoid rate limits.
  • Default Prompt Folder:
    • Directory where prompt templates are stored.
OpenAI Settings Dialog with Azure Options

2. MemoQ Server Configuration

Go to File → MemoQ configuration to manage server connections.

  • Connection Details:
    • Base Address: Server URL (e.g., https://example.company.com) without port.
    • Resources API Port: Port number for the Resources API (e.g., 8081).
    • WS API: WS API Port and Key (Optional, for Connected Mode).
  • Login Credentials:
    • Use a MemoQ user with Resource Lookup rights. (See MemoQ Documentation).
    • Nicknames: Save multiple logins with nicknames to switch easily.
  • Projects Folder:
    • Used for temporary storage of downloaded files, logs, and processed outputs.
    • Folder Size Warning: Set a threshold (MB) for disk usage alerts.
  • Treat same-language files as one:
    • Checked: Internal TM (fuzzy matches) is preserved across all files in a batch.
    • Unchecked: Matches reset for each file.
  • Important: Ensure the Resources API is enabled on your MemoQ server. It is free but may need to be activated by support.
MemoQ Configuration Dialog

3. Advanced Processing Settings

Go to File → Advanced processing settings to fine-tune the LLM behavior.

Advanced Processing Settings Dialog
  • LLM Parameters:
    • Temperature: Controls randomness (0.0 - 1.0). Lower values make the output more deterministic.
    • Verbosity: Controls the verbosity level of the model's output (Low, Medium, High).
    • Reasoning Effort: Controls how much time reasoning models (like gpt-5.1 or gpt-5.2) spend "thinking" before generating a response.
      Read more on reasoning effort here.
  • Thresholds & Limits:
    • Match Rate Threshold (%): The minimum similarity score required for a TM match to be included as an example.
    • Ref. Similarity Threshold (%): The minimum cosine similarity score required for a reference segment to be included in the context.
    • References per Segment: The maximum number of reference segments to inject for each source segment.
  • Processed Segment Status:
    • Choose the status to assign to segments after translation (e.g., "Machine Translated", "Edited", "Confirmed").
  • Tag Mapping:
    • Determines whether tags in the LLM response should be mapped to the Source or Target segments.
    • The response will contain placeholders like {{1}}, {{2}}. These are replaced by the actual tag content from the chosen segment. Note that extra or missing tags are not resolved automatically (unless Tag Contents is enabled, which repairs broken tag pairs — see below).
    • When Tag Contents is enabled, the tags legend describes the tags of the side selected here. With Target mapping, segments with empty targets have no tags to describe, and the legend may not match the source text's placeholders.
  • Populate JSON input schema:
    • Checked (Rich Schema Mode - Recommended): The application automatically injects segment data into a rich JSON structure. You can customize which fields to include and rename JSON keys. The field tick boxes are additive only: a field is sent when it is ticked here or named in the prompt, and nothing can stop a field the prompt names from being sent (see Input fields named in the prompt).
    • Unchecked (Legacy Mode): Uses simple text placeholders in the prompt.
    • Note: For detailed instructions, see the Prompting Guide.
  • Tag Contents ("tags" key):
    • Checked: Each segment in the JSON input gains a tags field describing what every {{1}}-style placeholder stands for — formatting tags show their type and pairing (e.g. "{{1}}": "[bpt:x-sup #1]", "{{2}}": "[ept #1]"), placeholder tags show their actual content (e.g. "{{1}}": "%userName%"), and masked special characters get a readable label (e.g. "{{3}}": "[non-breaking space]"). This lets the LLM decide whether a tag is needed in the target language and how to translate around it — see Working with the tags legend in the Prompting Guide for examples.
    • When enabled, PromptLoc also repairs broken formatting-tag pairs at write-back: if a response keeps only one half of an opening/closing pair, or places the closing tag before the opening one, the offending tags are removed instead of producing tag errors in memoQ.
    • Non-breaking spaces: PromptLoc replaces every non-breaking space (and the similar special spaces: thin, hair and narrow no-break space, line separator) in a segment with a {{n}} placeholder, exactly like a tag. This is deliberate. OpenAI models are known to mishandle the raw U+00A0 character: they silently turn it into a normal space, drop it, or return it as the literal text \u00a0 inside the JSON answer. A placeholder is a token the model can be told to keep, and when it keeps it PromptLoc restores the exact original character. If the model drops the placeholder there is nothing to restore and the space disappears. Enable Tag Contents so the model sees [non-breaking space] in the legend, and add the placeholder rules from Working with the tags legend to your prompt.
    • Unchecked (default): Requests are unchanged and all placeholders are expected to be preserved as before.
    • Note: Tags dropped by the model are still reported by memoQ's QA and PromptLoc's QA as source/target tag count differences — review those flags accordingly.

Interface & Operation Guide

Main Interface Overview

Write to (Output mode)

Use Write to to control where PromptLoc writes the model’s result:

  • Target: Writes the response into the target segment (updates the MQXLIFF).
  • Source: Writes the response into the source segment (updates the MQXLIFF).
  • Comment: Adds the response to the segment as a memoQ comment authored by PromptLoc. Source, target and segment status are left untouched. An empty response adds no comment, so a QA prompt can stay silent on correct segments. When you press Start, PromptLoc asks whether the existing PromptLoc comments on the processed segments should be removed first (Yes), kept (No), or whether to cancel. See the QA to Comments & Correction workflow.
  • CSV: Does not write back into the MQXLIFF at all. Instead, PromptLoc exports the inputs + the model response into a CSV file. This is useful for term extraction, QA checks, content analysis, or any workflow where you want results without modifying memoQ files.

CSV output location

When Write to = CSV, PromptLoc saves a file named *_processed.csv into a processed subfolder next to the source file.

What the CSV contains

  • In Rich Schema Mode, the CSV includes the enabled schema fields (using your configured JSON key names) plus a Response column.
  • In Legacy Mode, the CSV contains Source Text, Target Text, and Response.

Note: In Connected Project Mode, CSV export is a “read-only” workflow: the memoQ project is not updated because no MQXLIFF is written.

Outputs and Logging

  • Translated Files: Located in [SourceFolder]\PromptLocMT_Output\translated.
  • Logs: Located in [SourceFolder]\PromptLocMT_Output\logs.
  • UI Log: The Logs tab displays a real-time log of the process. You can click on log entries to see detailed JSON payloads and responses.

Job Queue & Batch Processing

The Queue tab allows you to manage multiple translation jobs.

  • Adding Jobs: Configure a file or folder and click "Add to queue" (or "Start" if the queue is empty). You can continue adding more jobs while the processor is running.
  • Monitoring: The list displays the status of each file (Queued, Running, Completed) and an estimated time of arrival (ETA).
  • Removing Jobs: Select one or more items in the queue and click "Remove Selected" to cancel them.

memoQ Resource Selection (TMs & TBs)

PromptLoc can use memoQ Translation Memories (TMs) and Term Bases (TBs) as context during processing. Resource selection is stored per file (especially important in folder/batch mode), and you can manage selections manually, via client-based matching, or automatically (when connected to a memoQ project).

1) Fully Manual Selection

In manual mode, you select resources directly from the available TM/TB lists:

  • Check the TMs and TBs you want to use for the current file.
  • Your selection is saved for that file and can differ across files in the same batch.
  • This is the default approach in Local Mode, and it’s also available in Connected Mode if you want to override server selections.
  • Use this when you want precise control or when no consistent client naming/assignment exists.

2) Match by Client (Semi-Automatic)

The Match by Client button helps you quickly find suitable resources using two filters:

  • Client IDs (entered manually)
  • The file’s language pair (parsed from the MQXLIFF)

How it works:

  • Clicking Match by Client opens a small dialog where you enter one or more Client IDs (comma-separated).
  • PromptLoc then searches the available memoQ resources and automatically selects:
    • TMs whose client matches one of the entered IDs and contain the file’s language pair
    • TBs whose client matches one of the entered IDs and support both languages

This mode is useful when your resources are consistently labeled with client IDs and you want a fast starting point, while still being able to fine-tune afterward.

3) Fully Automatic (Connected Project: Copy Server Assignments)

This option applies when you work in Connected Project Mode and download documents from a memoQ project.

  • PromptLoc retrieves the project’s TM/TB assignments from the server via the WS API.
  • These assignments are applied per downloaded document, based on the document’s target language.
  • In other words: the app doesn’t “guess” resources — it applies the server-side resource assignment blocks returned for each target language.

The Selected Tab (Overview + Remove)

The Selected tab is the quickest way to verify what will be used for the current file:

  • It shows the currently selected TMs and TBs for that file, regardless of how they were selected (manual, Match by Client, automatic).
  • In folder/batch mode, switching files updates the Selected tab to reflect that file’s saved configuration.

Removing resources (right-click)

  • You can remove one or more selected resources by right-clicking in the Selected list and choosing Remove.
  • Removing an item also clears its checkmark in the corresponding available TM/TB checklist.
  • This removal affects only the current file’s configuration (it does not change anything on the memoQ server).

Applying Settings to Multiple Files

When working with a folder or a project with multiple files, you can quickly propagate your settings.

  • Apply Resources: Click the arrow next to the "Apply for all" button (Resources section) to choose:
    • Same-language files in job: Applies the selected TMs/TBs only to files with the exact same language pair.
    • All files in job: Applies to every file in the list.
  • Apply Prompt: Similarly, use the "Apply for all" button in the Prompt section to use the current template for other files.

Prompt Selection & Client Metadata

  • Prompt Dropdown: Select a prompt template from your configured Default Prompt Folder.
  • Client Matching:
    • Prompt templates can contain a special metadata line: ### CLIENT METADATA: ClientName.
    • When you connect to a MemoQ project, the application reads the project's "Client" field.
    • Prompts that match the project's client are automatically prioritized (sorted to the top) in the dropdown list.
    • You can manually add client metadata to a prompt by selecting it while connected to a project; the application will ask if you want to add the current client to the template.

Modes of Operation

Local Mode

Available for all memoQ server users

  1. Go to your memoQ project and export file(s) and/or views in mqxliff.
  2. Open PromptLoc and select an individual .mqxliff file or a folder containing multiple files.
  3. Folder Mode: If you select a folder, a file list appears. You can navigate between files and apply settings individually or in bulk.
  4. Resource matching (TMs/TBs) must be done manually or via the "Match by Client" feature.
  5. Results are saved locally. You must manually import them back into MemoQ.

Connected Project Mode

Only available for users with the memoQ WS API

  1. Click "Connect to Project" to browse your memoQ project.
  2. Select a project and specific documents to download.
  3. Resources (TMs/TBs) are automatically matched based on the project settings on the server. Leave them as is or change as necessary.
  4. When processing completes, the processed/translated file is automatically uploaded to the server, and the project is updated.
MemoQ Project Update Illustration
Automatic project update in memoQ upon completion of the connected workflow.

Example Workflows

This guide provides example workflows for using PromptLoc in different scenarios. While many other use cases are possible, these examples cover the most common tasks.


1. Translation

This is the standard workflow for translating documents using the power of LLMs combined with MemoQ resources.

Configuration

  • Write to: Set to Target.
  • Resources: Ensure relevant Translation Memories and Term Bases are selected to provide context.

Example Prompts

For detailed instructions on constructing these prompts, see the Prompting Guide.

Legacy Mode Prompt:

You are a professional translator. Translate the following %SOURCELANG% text into %TARGETLANG%.
Use the following terminology:
%TERMS%
Use these examples for style:
%EXAMPLES%

Rich Schema Mode Prompt:

You are a professional translator. Translate the JSON segments from %SOURCELANG% into %TARGETLANG%.
Input Format:
- "source_text": The text to translate.
- "terms": Mandatory terminology.
- "memoq_examples": Past translation examples.

Return a JSON object with the translated text for each segment key.

2. Revision

In this workflow, you use the LLM to review or edit existing translations (e.g., from a different engine or a human draft). This requires the Rich Schema Mode.

Configuration

  • Write to: Set to Target (this overwrites the existing target with the revised version).
  • Schema Settings:
    • Enable Populate JSON input schema.
    • Target Text is sent automatically because the prompt names it (see Input fields named in the prompt); ticking it is no longer required.
    • You might rename the key target_text to draft_translation in the settings to make it clearer for the LLM. The prompt must then use the new name.

Example Prompt (Schema Mode Only)

Ensure you follow the structure defined in the Prompting Guide.

You are a senior editor. You will receive a JSON object where each segment contains:
- "source_text": The original source.
- "draft_translation": A draft translation that needs review.
- "terms": Mandatory terminology.

Your task is to revise the "draft_translation" to ensure accuracy and fluency.
- Fix any terminology errors based on the "terms" provided.
- Improve style and grammar.
- If the draft is perfect, return it unchanged.

Return a JSON object with the revised translations.

Scenario 2: Tag Fixing

Download Tag Fixer Prompt

This scenario addresses common issues where tags in the target text are misplaced, missing, or incorrectly formatted due to translation errors or external plugin artifacts. Such errors include disordered tags, stripped formatting (bold/italic), or incorrect spacing.

You can use a specialized "Tag Fixer" prompt (downloadable above) to automatically identify and correct these tag problems, ensuring the target structure matches the source. Note that for extremely tag-heavy segments, manual review may still be necessary.

Tag problems before

Before: Tag errors in MemoQ

Tag problems after

After: Corrected tags


3. Preparation (Source Rephrasing)

This workflow is useful when the source text is poorly written (e.g., machine-generated or non-native speaker) and you want to improve it before translation, or if you simply need to paraphrase text.

Configuration

  • Write to: Set to Source (this overwrites the source segment in the MQXLIFF).
  • Schema Settings:
    • Enable Populate JSON input schema.
    • Check Source Text.
    • Uncheck other context fields like references or terms if they are not relevant for rephrasing.

Example Prompt

Refer to the Prompting Guide for available fields and options.

You are a copywriter. Your task is to rewrite the provided "source_text" to be clear, concise, and grammatically correct English.
- Do not translate the text.
- Preserve the original meaning.
- Fix any typos or awkward phrasing.

Return a JSON object with the rewritten source text.

Scenario 2: Tagging Source Text

Download Source Tagger Prompt

Modifying the source text may be necessary sometimes, particularly when standard regex taggers fail to capture complex patterns like product codes or SKUs.

This workflow uses a focused prompt (downloadable above) designed to strictly identify and wrap these elements in tags without altering any other part of the text, enabling downstream tools to recognize them as content to tag.

Source tagging before

Original source text in MemoQ (hard to tag with regex)

Configuration

  • Write to: Set to Source.
Write to Source setting

It is recommended to uncheck unnecessary JSON keys for this task (e.g., references or examples), and perhaps rename source_text to text_to_tag to be more explicit (though optional).

JSON Key settings

Once the processed file is updated in MemoQ, all identified taggable content is in a uniform format (e.g., between < >), enabling you to use the Regex tagger effectively.

Source tagging result

Result: Uniformly tagged source text


4. Term Extraction (CSV Export)

Download Term Extraction Prompt

This workflow is designed for terminology extraction from bilingual content without changing anything in memoQ. Instead of writing back into MQXLIFF, PromptLoc exports the results to a CSV, which you can review, filter, and process further before importing into a termbase or other tools.

Configuration

  • Write to: Set to CSV.
    (Non-destructive: no changes are written to Source or Target segments in the MQXLIFF.)
  • Schema Settings (recommended):
    • Enable Populate JSON input schema.
    • Enable Source Text.
    • Enable Target Text if you want to extract bilingual term pairs from an existing translation.
    • (Optional) Enable terms, forbidden_terms, and memoq_examples if you want the model to respect existing terminology or reuse TM wording.
  • Prompt template: Use the dedicated Terminology Extraction prompt.

How it works

For each segment, the model returns a single string that contains:

  • One or more term pairs formatted as: Source root form = Target root form
  • Multiple pairs separated by semicolons (;)
  • A placeholder value (for example -) when no valid term candidates are found

Result

After processing, PromptLoc creates a *_processed.csv file in the processed output folder. The CSV contains the enabled schema fields plus a Response column holding the extracted term data.

Note on post-processing the CSV:

The extracted terminology is returned as a compact string format, which typically requires additional processing before it can be used as a termbase:

  • Split multiple term pairs into separate rows using ;
  • Split each pair into Source term and Target term using =
  • Normalize casing and whitespace
  • Deduplicate term pairs
  • If multiple valid equivalents are allowed for a single source term, you may need an extra step to split or duplicate rows accordingly

This extra processing step is intentional: it keeps PromptLoc flexible and allows you to adapt the output to the exact structure required by your terminology management workflow.


5. QA to Comments & Correction

Three jobs on the same document, with no manual step in between: translate, check, correct. The check writes its findings into memoQ as comments, the correction reads those comments and changes only the segments that have one. The comments stay on the segments as the QA record, and memoQ keeps a document version for every job.

Configuration

  1. Translate: your usual translation prompt, Write to: Target.
  2. Check: the QA prompt, Write to: Comment. Answer Yes to the question at Start so that comments of an earlier check are replaced.
  3. Correct: the revision prompt, Write to: Target. Set the segment status to Confirmed if no human check follows. Do not remove the PromptLoc comments on this job: it needs to read them.

Both prompts name target_text and comments, so the existing translation and the QA comments are sent without any change to the schema settings. In Connected Project Mode every job uploads its result and the next job fetches the current version of the document, so the three jobs can simply be queued one after the other.

The QA prompt

The prompt checks each segment against a fixed list of objective errors (meaning, omissions, numbers, names, terminology, grammar, tags) and answers with an empty string for a correct segment, which adds no comment. A finding is one line with a fixed shape, so it can be read, filtered and exported from memoQ:

[QA] Critical | Accuracy: the source says the employee must not work overtime, the target says 'deve'. Fix: non deve.

Condensed from the downloadable prompt:

You are a senior bilingual QA reviewer. Your task is NOT to translate and NOT to rewrite. Your task is ONLY to check each existing translation and report objective errors as a short comment.

Each segment contains:
- `source_text`: The original text.
- `target_text`: The existing translation to check.
- `terms`: Mandatory terminology pairs. `forbidden_terms`: Terms that must not be used.
- `comments`: Existing comments. Comments that start with [QA] come from an earlier QA run: ignore them.

Check every segment for: inverted negation or modality, omissions, additions, mistranslation, wrong numbers or dates, altered proper names, untranslated text, missing required terms, forbidden terms, grammar and spelling errors, wrong number or date format, missing or misplaced {{1}}-style tags.
Do NOT report style, synonym choice or anything you are not sure is a real error. When in doubt, the segment passes.

Output rules:
- Return a JSON object whose keys match the input keys and whose values are strings.
- A correct segment gets exactly an empty string: "". Never write OK or null.
- A segment with an error gets: [QA] Severity | Category: what is wrong. Fix: the corrected wording.
- Severity is Critical, Major or Minor. Keep each finding under 40 words, no line breaks.

The revision prompt

The prompt distinguishes three cases per segment and is strict about leaving everything else alone:

You are a senior bilingual reviser. Your task is ONLY to correct the errors that the QA reviewer reported in the comments, and to leave everything else exactly as it is.

Each segment contains `source_text`, `target_text`, `comments` (a QA finding starts with [QA]), `terms`, `forbidden_terms` and `memoq_examples`.

Case A - no comment that starts with [QA]: return `target_text` exactly as it is, character for character.
Case B - one or more [QA] findings: start from `target_text`, check each finding against `source_text`, and fix it with the smallest possible change, using the wording after "Fix:" as guidance. If the problem is no longer present, or the finding is clearly mistaken, change nothing for it.
Case C - `target_text` is missing: translate `source_text`.

Never return an empty string. Never copy the comment or the [QA] prefix into the output. Preserve all {{1}}-style tags with the same count and order.

The same chain runs unattended from the command line as one command, see Several steps in one run.


Other Use Cases

These are just a few examples. PromptLoc is flexible:

  • Transliteration: e.g., Serbian Cyrillic and Latin.
  • Text expansion/shrinking: Adjusting text length constraints.
  • Tagging source: Tagging content that would be hard to capture with classic regex based rules.
  • Style Adaptation: Use prompts to rewrite the target text into a specific tone (e.g., "Marketing", "Formal", "Playful").

Experiment with different prompts and schema configurations to find what works best for your project!

The References Function: Semantic Search

The Reference Function is one of the most powerful tools in PromptLocMT. It allows the AI to "read" an entire external document (like a law, a manual, or a style guide) and only pick the relevant parts for each sentence it translates.

Semantic Search: The "Magic" Behind References

Unlike traditional Translation Memories (TMs) and LiveDocs which look for matching words, the Reference function uses Vector Embeddings (Semantic Search).

Key Concept: Meaning over Matching Strings

The relevant reference lines do not have to share any strings with the translatable text to match. The AI matches based on meaning.

For example, if your source text says "The tenant must pay by the 5th", the tool can find a reference line in a law saying "Rent is due in the first week", even though they share almost no words.

Example Scenario: Legal Translation

Scenario: You are translating a Lease Agreement from English to Spanish.
Setup: You load the Spanish Civil Code (in Spanish) as your Reference file.

Source Text (English) Matched Reference (Spanish Law) Why it matched
"The tenant shall be liable for any damages caused to the property." "La parte que cause daños a la otra parte por incumplimiento del contrato será responsable..." (Liability for damages caused by breach...) Semantic Match. The AI knows "liable for damages" equates to the legal concept in the reference line, even across languages.

Result: The AI uses the official legal terminology found in the reference when generating the translation.

Bonus Tip: Unaligned Documents

If you have unaligned document pairs, you can skip alignment if you use this function. You can just load your existing translations as reference and it will not only pull the most relevant bits to each translation segment (practically aligning them) but also adapt and correct them if the sentence pairs are not perfect translations of each other.


How to Prepare & Load References

1. Preparation (.txt)

Create a standard .txt file (UTF-8). The rule is simple: One Line = One Chunk.

Section 6:142 [Liability for breach of contract]
The party who causes damage to the other party by breaching the contract shall be liable...
Unless he proves that the breach of contract was caused by a circumstance outside his control...
Section 6:143 [Foreseeability]
Damages shall be compensated to the extent that the obligee proves...

Each line above becomes a searchable "chunk" for the AI.

2. Loading

In the main settings window, look for the References field. Click "Browse" and select your .txt file.

First Run Delay: The first time you use a new reference file, the tool will take some time (this depends on the settings, e.g. embedding batch size, and the length of your reference file) to "embed" it (send it to OpenAI to be converted into vectors). It saves these as a hidden _embeddings.json file so next time it is instant.


Language Independence

References are language agnostic. You can mix languages in the same file.

  • Source-Language References: Good for explaining concepts or obscure acronyms.
  • Target-Language References: If relevant unaligned existing translations are available.
  • Mixed: You can have a file with both source and target language reference texts. The AI will pull the relevant ones based on meaning.

Prompting with References

To use these references, your Prompt Template needs to know where to put them. See the Prompting Guide for full details on placeholders and JSON fields.

1. Legacy Mode (Simple)

Use the %REFERENCES% placeholder. The AI will see only the most relevant lines extracted from your file.

Example Prompt:

You are a legal translator. Translate the following text into %TARGETLANG%.

Here are some relevant excerpts from the applicable law that may guide your terminology:
"""
%REFERENCES%
"""

Source Text: ...

2. Rich Schema Mode (Advanced)

In this mode, references are injected directly into the JSON object for each segment. You do not need a placeholder, but you should instruct the AI to look at the references field.

Example Prompt:

You are a legal translator. You will receive a JSON object where each segment contains:
- "source_text": The text to translate.
- "references": Relevant excerpts from applicable laws or manuals.

Instructions:
Translate the "source_text" into %TARGETLANG%.
- Review the "references" provided for each segment.
- Use the terminology and style found in the "references" to ensure legal accuracy.

This application supports two distinct prompting modes: Legacy Mode (Simple) and Rich Schema Mode (Advanced). The mode is determined by the "Use JSON Schema" setting in the Processing Settings.

Crucial Instructions

Regardless of the mode, you must explicitly include instructions in your prompt to handle context and tags. We recommend adding the following directives to your prompt template:

  • Context: "Ensure that the translation maintains the context and continuity across different segments and sections of the json structure to preserve the coherence and meaning of the original text. This should be true not only within messages, but also across messages in the conversation."
  • Tags: "Maintain the exact structure of the original document. Placeholders in the form {{1}}, {{2}} stand for protected tags or non-breaking spaces. Copy every placeholder into the translation, unchanged and at the equivalent position; never drop, merge, reorder or invent placeholders."

1. Legacy Mode (Simple JSON)

In this mode, context (glossaries, examples, etc.) is injected directly into the text of your prompt using placeholders. The input data sent to the LLM is a simple JSON dictionary of source segments.

Placeholders

You must include these placeholders in your prompt template. The application will replace them with the relevant data before sending the request to the LLM.

Placeholder Description
%SOURCELANG% The name of the source language (e.g., "English").
%TARGETLANG% The name of the target language (e.g., "German").
%TERMS% A list of allowed terms found in the Termbase (TB), formatted as source = target.
%FORBIDDENTERMS% A list of forbidden terms found in the TB, formatted as source ≠ target.
%REFERENCES% Relevant reference segments found in the reference files or embeddings.
%EXAMPLES% Translation examples (fuzzy matches) found in the Translation Memory (TM), formatted as Source\nTarget pairs.

Input Data Structure

The LLM receives the prompt followed by a simple JSON object containing the segments to translate:

{
  "segment1": "The source text for the first segment.",
  "segment2": "The source text for the second segment."
}

Example Legacy Prompt

You are a professional translator translating from %SOURCELANG% to %TARGETLANG%.

Use the following terminology:
%TERMS%

Avoid these forbidden terms:
%FORBIDDENTERMS%

Use these references for context:
%REFERENCES%

Here are some examples of past translations:
%EXAMPLES%

Translate the following JSON segments. Return only the translated JSON object.

2. Rich Schema Mode (Advanced)

In this mode, context (terms, examples, references) is not injected into the prompt text. Instead, it is structured inside the input JSON object itself for each segment. This allows for granular, segment-level context.

Placeholders

Most placeholders are disabled in this mode because the data is in the JSON.

Placeholder Behavior in Schema Mode
%SOURCELANG% Active. Replaced with the source language name.
%TARGETLANG% Active. Replaced with the target language name.
%TERMS% Removed. (Data is in the terms JSON field).
%FORBIDDENTERMS% Removed. (Data is in the forbidden_terms JSON field).
%REFERENCES% Removed. (Data is in the references JSON field).
%EXAMPLES% Removed. (Data is in memoq_examples or internal_examples JSON fields).

Input Data Structure

The LLM receives the prompt followed by a rich JSON object. Your prompt must instruct the LLM to read this structure.

{
  "segment1": {
    "source_text": "The text to translate.",
    "tags": { "{{1}}": "[bpt:bold #1]", "{{2}}": "[ept #1]" },
    "terms": { "term": "translation" },
    "forbidden_terms": [ { "source": "bad_term", "forbid": ["avoid_this"] } ],
    "references": [ "Similar sentence context..." ],
    "memoq_examples": [ { "source": "Old source", "target": "Old target" } ],
    "maxlength": 100
  },
  ...
}

JSON Fields

The keys used in the input JSON can be customized in the Processing Settings. The defaults are:

  • source_text: The segment text to be translated.
  • target_text: Existing target text (if any).
  • terms: Dictionary of mandatory terms for this segment.
  • forbidden_terms: List of terms to avoid for this segment.
  • references: Contextual reference text specific to this segment.
  • memoq_examples: TM matches from MemoQ.
  • internal_examples: Fuzzy matches from within the current file batch.
  • comments: Comments from the XLIFF file.
  • maxlength: The maximum allowed length for the translation (if > 0).
  • tags: Description of each {{1}}-style placeholder in the segment (only when Tag Contents is enabled; the key name is fixed).

Input fields named in the prompt

The prompt decides which fields it needs. Every field the prompt names is sent, in the UI and in the CLI, even when it is not ticked under Populate JSON input schema in the Advanced Processing Settings. Ticked fields are still sent when the prompt does not name them.

The rule is additive only. The set of fields sent is the union of the ticked fields and the fields the prompt names: ticking a field adds it, naming a field in the prompt adds it, and neither can remove a field the other one added. There is no way to un-tick a field for a prompt that names it; if a prompt should not receive a field, remove the field from the prompt. A prompt names a field when the key appears

  • in backticks or quotes anywhere in the prompt: `terms`, "comments";
  • as a bare word, if the key contains an underscore: target_text, forbidden_terms;
  • at the start of a line followed by a colon: terms: Mandatory pairs.

The key must be spelled as configured in the settings: if you renamed target_text to draft_translation, the prompt has to say draft_translation. The job log lists the fields the prompt switched on, and it warns when a named field has nothing to send in this job (no term base or translation memory selected, no reference file, no segment with a target text or a comment, or a field name PromptLoc does not provide).

Working with the tags legend

With Tag Contents enabled (under File → Advanced Processing Settings), the model can make two kinds of decisions it cannot make from bare {{1}}-style placeholders.

1. Dropping tags that serve no purpose in the target language. English marks ordinals with superscript letters; Spanish dates use none. The model sees that the pair around "st" is superscript and may omit it:

Input:  { "source_text": "The meeting takes place on March 21{{1}}st{{2}}.",
          "tags": { "{{1}}": "[bpt:x-sup #1]", "{{2}}": "[ept #1]" } }
Output: "La reunión tendrá lugar el 21 de marzo."

Both halves of the pair are omitted together (#1 marks which opening and closing tags belong together). The same applies to masked special characters:

Input:  { "source_text": "The licence costs 12{{1}}000 EUR per year.",
          "tags": { "{{1}}": "[non-breaking space]" } }
Output: "La licencia cuesta 12.000 EUR al año."

Here the non-breaking space used as a thousands separator disappears, because the Spanish convention replaces it with a dot.

2. Translating correctly around content placeholders. Variables never get dropped, but the legend tells the model what kind of value will fill the slot — which target-language grammar often depends on. These two segments are identical without the legend, yet need different Spanish structures:

Input:  { "source_text": "The message was sent to {{1}}.",
          "tags": { "{{1}}": "%userName%" } }
Output: "El mensaje se envió a {{1}}."

Input:  { "source_text": "The message was sent to {{1}}.",
          "tags": { "{{1}}": "%channelName%" } }
Output: "El mensaje se envió al canal {{1}}."

A person takes the personal a; a channel takes the contraction al plus a support noun. The same mechanism drives gender agreement on inserted support nouns:

"Are you sure you want to delete {{1}}?"
  with "{{1}}": "%fileName%"     → "¿Seguro que quieres eliminar el archivo {{1}}?"
  with "{{1}}": "%playlistName%" → "¿Seguro que quieres eliminar la lista de reproducción {{1}}?"

and article decisions: {{1}} is not responding. becomes "La aplicación {{1}} no responde." when the legend says %appName%, but simply "{{1}} no responde." when it says %contactName%.

Prompt requirements. The legend only grants the ability — your prompt must grant permission and set the rules. Add instructions along these lines:

  • Placeholders like {{1}} are the only way to reference tags; never write tag contents or legend labels into the translation.
  • Keep every placeholder whose formatting or content is needed in the target language; you may omit one whose tag serves no purpose there.
  • Opening/closing pairs (matching #n markers) must be kept or omitted together.
  • Placeholders holding content (variables, images, footnote references, hyperlinks) must always be kept.
  • Placeholders labelled [non-breaking space] must be kept wherever the target language also uses a non-breaking space, for example between a number and its unit, and before %, § and currency symbols. Keep them between the same two elements as in the source.
  • Only omit a whitespace placeholder when the target-language convention has no space there at all (for example a thousands separator written as a dot). If a normal space is needed instead, write a plain space.
  • If a segment has no tags field, keep all placeholders exactly as they appear.

A complete, ready-to-use prompt with these instructions already integrated is available for download — the default Schema Mode + Developer prompt with the tags field documented, the tag-handling instruction, and the matching verification checks built in. If you already maintain a customized prompt, the add-on variant contains only the tag-related blocks with notes on where each part goes.

Download full prompt (.txt) Download add-on for existing prompts (.txt)

Resource Prioritization

If Include TM/TB names in JSON context is enabled under File -> Advanced Processing Settings, PromptLoc can add memoQ resource names to the rich JSON context. For example, memoq_examples entries may include tm_name, while TB-derived term data may include tb_name or tb_names. PromptLoc does not enforce priority automatically; you can use these fields in your prompt to tell the model which resources should win when context sources disagree.

Example: prioritize one TM over other examples and drafts

Priority TM rule:
Some `memoq_examples` entries may include `tm_name`, indicating the memoQ translation memory they came from. Treat examples from `tm_name: "Client_Master_TM"` as the highest-priority translation memory evidence.

Priority order:
1. If a `memoq_examples` entry from `Client_Master_TM` is an identical source match, reuse its target translation exactly unless it violates forbidden terms, tag/placeholder preservation, or the required JSON output format.
2. If a `memoq_examples` entry from `Client_Master_TM` is a close or partial match, follow its terminology, phrasing, register, and style as the primary reference, adapting only what is needed for the current source text.
3. When `Client_Master_TM` conflicts with other `memoq_examples`, `internal_examples`, or `target_text`, prefer `Client_Master_TM`.
4. Never use a `Client_Master_TM` example to justify forbidden terms, broken grammar, mistranslation, missing content, altered proper names, or changed/missing tags.

Example: prioritize a TM against terminology, with guardrails

Priority TM vs terminology:
When a `memoq_examples` entry from `Client_Master_TM` conflicts with `terms`, prefer the `Client_Master_TM` example if it is an identical or very close match and fits the current context.

Use `terms` instead of the TM example when:
1. The term is clearly mandatory for the current client, product, legal, technical, or UI context.
2. The TM example is outdated, mistranslated, incomplete, ungrammatical, or inconsistent with the source segment.
3. The TM example would introduce a forbidden term, alter required tags/placeholders, or break the required JSON output format.

If both are acceptable, choose the wording that best preserves client consistency and natural target-language style.

Example: prioritize one TB when termbases disagree

Priority TB rule:
Some terminology entries may include `tb_name` or `tb_names`, indicating the memoQ termbase they came from. Treat entries from `Client_Approved_TB` as the highest-priority terminology evidence.

Priority order:
1. If duplicate or conflicting terms are provided, prefer entries where `tb_name` is `Client_Approved_TB` or `tb_names` contains `Client_Approved_TB`.
2. Apply the preferred TB term consistently across all relevant segments, unless it is clearly inappropriate for the current context.
3. If a lower-priority TB conflicts with `Client_Approved_TB`, ignore the lower-priority term unless the preferred term is clearly wrong.
4. Never use a preferred TB term if it appears in `forbidden_terms` or would break grammar, meaning, tags/placeholders, or the required JSON output format.

Example Schema Prompt

You are a highly skilled translator. You will be provided with a JSON object containing segments to translate from %SOURCELANG% into %TARGETLANG%.

Input Structure:
The input is a JSON object where each key (e.g., "segment1") represents a text segment. Each segment value is an object containing:
- `source_text`: The text to translate.
- `terms`: A dictionary of mandatory terminology (source -> target).
- `forbidden_terms`: A list of terms to avoid.
- `references`: Contextual reference text.
- `memoq_examples` / `internal_examples`: Previous translation examples for style/consistency.
- `maxlength`: Maximum allowed length for the translation (if > 0).

Instructions:
Translate each `source_text` into %TARGETLANG%.
- Strictly adhere to the `terms` provided for each segment.
- Use `examples` and `references` to guide your style and consistency.
- Return a single JSON object where keys match the input (e.g., "segment1") and values are the translated strings.

Verification Checks

Verification checks are an advanced prompting technique. By asking the model to explicitly "verify" its work before finalizing the output, you encourage a "Chain of Thought" process. This self-correction step significantly reduces hallucinations and improves adherence to strict constraints (like tags or terminology).

Include a section like this at the end of your prompt:

Verification Steps:
Before outputting the final JSON, perform the following checks silently:
1. Consistency: Verify that if an identical sentence exists in the examples, the exact translation is reused; if a similar sentence is available, adapt it only as necessary.
2. Context: Verify that the translation fits the context of previous messages and the JSON structure.
3. Format: Verify that the response contains only the valid JSON object and no conversational text.
4. Tags: Verify that the number and order of tags (e.g., {{1}}) match the source exactly. Ensure no whitespace is added around tags unless present in the source.
5. Terminology: Verify that all glossary terms are used correctly and no unauthorized synonyms are introduced.

After verifying, output the final JSON.

Advanced: Developer Prompts

You can optionally separate the "Developer" (System) instructions from the rest of the prompt. This allows you to define a persona and strict rules that the model should prioritize.

To use this feature, enclose the developer instructions between ### DEVELOPER_START and ### DEVELOPER_END markers:

### DEVELOPER_START
You are a highly skilled translator... [System Instructions]
### DEVELOPER_END

[Rest of the prompt / User Message]

CLI Options

PromptLoc supports a headless Command Line Interface (CLI) mode for integrating into automated workflows through the memoQ WS API. One run can process several documents of the same project in a single memoQ session, which is the recommended way to automate large batches of small files.

Usage

PromptLocMT.exe --cli --project <GUID> --document <GUID>[,<GUID>...] --prompt <path_to_template> [options]
PromptLocMT.exe --cli --project <GUID> --documents <list_file> --prompt <path_to_template> [options]
PromptLocMT.exe --cli --project <GUID> --document <GUID>[,<GUID>...] --steps <steps_file> [options]

Required Arguments

Argument Description
--cli Activates the CLI mode. Without this, the application launches the GUI.
--project <GUID> The MemoQ Project GUID. (memoQ project templates can pass this as a parameter)
--document <GUID>[,<GUID>...] One or more MemoQ Document GUIDs to translate, separated by commas or semicolons. (memoQ project templates can pass this as a parameter)
--documents <path> Alternative to --document: a text file with one document GUID per line. Blank lines are ignored, # starts a comment. Can be combined with --document.
--prompt <path> Absolute path to the text file containing the prompt template.
--steps <path> Alternative to --prompt: a text file listing several prompts to run one after the other on the same documents. See Several steps in one run.

All documents of one run must belong to the project given in --project. They are exported, translated and, with --update, uploaded one after the other inside one memoQ session, so a batch of many files costs one login instead of one login per file.

Optional Arguments

Argument Description Default
--model <name> The OpenAI model to use (e.g., gpt-6.1-sol, gpt-6-luna). User Settings
--reasoning <val> Reasoning effort: low, medium or high. User Settings
--status <val> Status assigned to processed segments: MachineTranslated, PreTranslated, Edited, Confirmed, NotStarted or Preserve (keep the original status). User Settings
--apikey <key> OpenAI API key for this run only. It is not saved. User Settings / --config bundle
--no-tm Do not use the translation memories assigned to the project. TMs are used
--no-tb Do not use the termbases assigned to the project. TBs are used
--batch <num> Number of segments to process in a single API request. User Settings
--history <num> Number of previous messages to include as context. User Settings
--writeto <val> Where the response is written: Target, Source, Comment (a memoQ comment on the segment, nothing else changes) or CSV. Any other value stops the run. Target
--clean-comments Only with --writeto Comment: replaces the existing comments authored by PromptLoc on every segment the run processes. Comments by other users are kept. false
--include-target Sends the existing target text even if the prompt does not name target_text. Rarely needed: a prompt that names the field gets it automatically. false
--workdir <path> Directory to download/process files in. User Settings
--update If present, uploads each translation back to the MemoQ server and updates the document. false
--config <path> Load credentials from a machine-encrypted bundle created with --export-service-config (for service accounts and scheduled tasks that never open the GUI).
--export-service-config <path> Export the current memoQ credentials, OpenAI settings and license as an encrypted bundle for use with --config. The bundle can only be decrypted on the machine that created it, by any account on that machine, so keep it in a folder with restricted permissions.
--version Print the application version and exit.
--help Print the option list and exit.

Settings not given on the command line are taken from the values saved in the GUI (File → Advanced processing settings and File → OpenAI settings).

Exit Codes

Code Meaning
0 Every requested document was processed.
1 At least one document failed (export, download or translation), or the arguments were invalid. Details are printed to stderr and written to cli_debug.log.
2 License validation failed.

Note: In a plain --prompt run a failed --update upload is reported on stderr but does not change the exit code. In a --steps run it fails the document, because the next step would otherwise work on the old content.

Several Steps in One Run

--steps <file> runs several prompts on the same documents in one go, for example translate, then check, then correct. PromptLoc starts once, logs in to memoQ once, runs the steps in order and logs out once at the end, so the steps do not wait for memoQ's login throttling between them.

The steps file has one step per line: the prompt file first, then the options for that step.

# translate, check, correct
translation_prompt.txt
qa_comment_prompt.txt                --writeto Comment --clean-comments
revision_from_comments_prompt.txt   --status Confirmed
  • Blank lines and lines starting with # are ignored. A path with spaces goes in double quotes. A relative prompt path is resolved against the folder of the steps file.
  • A step accepts --writeto, --status, --clean-comments, --include-target, --reasoning, --model, --batch, --history, --no-tm and --no-tb. An option set on one step does not carry over to the next. --model, --reasoning, --batch, --history, --no-tm and --no-tb given on the command line apply to every step that does not set its own.
  • --prompt, --writeto, --status, --clean-comments and --include-target cannot be combined with --steps; they belong on a step's line. --writeto CSV is only possible on the last step.
  • The whole file is checked first. A missing prompt file or an invalid option stops the run before any document is touched, with every problem listed by line number.
  • A document that fails a step is not passed on. If the check fails for a document, the correction never runs for it, so it cannot end up confirmed without having been checked. The other documents of the run continue.
  • With --update every step uploads its result and the next step downloads the document again, so memoQ keeps a version per step. Without --update nothing is uploaded and each step continues on the local result of the step before.
  • Each step keeps its input, result and job log in its own folder: [workdir]\[DocumentGuid]\step1, step2, and so on. Each step prints Step 2 of 3 completed: <GUID> or, on stderr, Step 2 of 3 failed: <GUID> (...); at the end there is one Completed: or Failed: line per document, as in a plain run. Exit code 0 only when every document went through every step.

Examples

1. Basic Translation (Default Settings)

Downloads the document, translates it using your saved settings (model, history, etc.), and saves the result locally.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p" --prompt "C:\Prompts\GeneralTranslator.txt"

2. Custom Model & Batch Size

Overrides user settings saved through the GUI to use a specific model and larger batch size.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p" --prompt "C:\Prompts\TechnicalDocs.txt" --model "gpt-6.1-sol" --batch 30

3. Full Automation (Translate & Update Server)

Translates the file and immediately uploads it back to the MemoQ server, updating the document in place.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p" --prompt "C:\Prompts\Marketing.txt" --update

4. Write to Source Column

Useful for correcting grammar in source text before translations.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p" --prompt "C:\Prompts\SourceChecker.txt" --writeto "Source"

5. Many Documents in One Run

Processes a whole list of documents in one memoQ session. documents.txt holds one GUID per line.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --documents "C:\Jobs\documents.txt" --prompt "C:\Prompts\GeneralTranslator.txt" --status Confirmed --update

The same works inline for a few documents:

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p,4b5c6d7e-8f9g-0h1i-2j3k-4l5m6n7o8p9q" --prompt "C:\Prompts\GeneralTranslator.txt"

6. Higher Reasoning, No Project Resources, Separate API Key

Runs with medium reasoning, ignores the project's TMs and TBs, and bills the run to a different OpenAI key.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p" --prompt "C:\Prompts\Creative.txt" --reasoning medium --no-tm --no-tb --apikey "sk-..."

7. Translate, QA Into Comments, Correct: One Run

The QA to Comments & Correction workflow as one command. steps.txt is the three-line file shown above; the QA and revision prompts are available for download there.

PromptLocMT.exe --cli --project "7f8e9d0a-1b2c-3d4e-5f6g-7h8i9j0k1l2m" --document "3a4b5c6d-7e8f-9g0h-1i2j-3k4l5m6n7o8p" --steps "C:\Prompts\steps.txt" --update

Both prompts name target_text and comments, so the existing translation and the QA comments are sent without any extra switch. Do not put --clean-comments on the revision step: it needs to read the QA comments.

Notes

  • Authentication: The CLI uses the credentials stored in MemoQCredentials.dat and OpenAISettings.dat in the user's AppData, or the bundle given with --config. You must run the GUI version at least once to configure these settings.
  • memoQ session: The CLI logs in to the memoQ Resources API when the first TM/TB lookup needs it and logs out when the process ends, releasing the session and its license. memoQ throttles logins (TooFrequentLogins) and limits concurrent sessions, so prefer one run with many documents over many runs with one document each, and --steps over one run per prompt. If you must start separate runs, leave about 30 seconds between them.
  • Logs: Startup and fatal errors go to cli_debug.log in the application directory. Each document gets its own detailed job log next to the downloaded file: [workdir]\[DocumentGuid]\[DocumentGuid]_log.txt. The compact monthly usage log in %LOCALAPPDATA%\PromptLocMT\logs\usage\usage_YYYY-MM.txt is written as well.