From 017cc122671286b3dadcdc874e02cccf9b326657 Mon Sep 17 00:00:00 2001 From: Jan Cizmar Date: Thu, 9 Jul 2026 18:53:49 +0200 Subject: [PATCH 1/2] docs: document escapeJson helper in AI playground Adds a helpers section describing escapeJson, with an example of building a structured JSON prompt and a note about which YAML scalar styles it suits. --- .../translation_process/ai_playground.mdx | 31 ++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/platform/translation_process/ai_playground.mdx b/platform/translation_process/ai_playground.mdx index 824072222..61ef5964a 100644 --- a/platform/translation_process/ai_playground.mdx +++ b/platform/translation_process/ai_playground.mdx @@ -114,7 +114,7 @@ In this view, you can change each language's machine translation settings global ## Handlebars templating system -To use a variable, start by typing `{{` (double curly bracket), and the editor will hint you at available variables and fragments. +To use a variable, start by typing `{{` (double curly bracket), and the editor will hint you at available variables, fragments and helpers. Date: Thu, 9 Jul 2026 20:55:50 +0200 Subject: [PATCH 2/2] docs: address review on escapeJson section Moves the helper to the end of the page, drops the single-row table, and corrects the motivation: models rarely need structured payloads, but escaping guards a value from breaking out of its string. --- .../translation_process/ai_playground.mdx | 62 ++++++++++--------- 1 file changed, 32 insertions(+), 30 deletions(-) diff --git a/platform/translation_process/ai_playground.mdx b/platform/translation_process/ai_playground.mdx index 61ef5964a..49bdf7212 100644 --- a/platform/translation_process/ai_playground.mdx +++ b/platform/translation_process/ai_playground.mdx @@ -164,35 +164,6 @@ Common properties for translation/language of `source`, `target` and `other.{tag | .isCJK | Is Chinese, Japanese or Korean | false | -## List of available helpers - -Helpers transform a value before it is inserted into the prompt. To use one, type it right after -`{{` and pass the variable as its argument. - -| Name | Description | Example | -|------------|-----------------------------------------------------------------------------------------------------------------|------------------------------------| -| escapeJson | Escapes quotes, newlines and backslashes in the value, so it can be safely embedded inside a JSON string | \{\{escapeJson key.description}} | - -### Building a structured prompt - -Some models expect a structured payload rather than prose. Without escaping, a key description that -contains a quote or a newline produces invalid JSON. Wrap each value in `escapeJson` to prevent that: - -```handlebars -{ - "context": "{{escapeJson key.name}} {{escapeJson key.description}}", - "text": "{{escapeJson source.translation}}", - "locale": "{{target.languageTag}}" -} -``` - -`escapeJson` is safe to use on any variable — applying it to a value that is already escaped returns -the value unchanged, so it never escapes twice. - -The result is escaped for a JSON string. It is also valid inside a **double-quoted** YAML scalar, but -not inside single-quoted, plain or block scalars, where a backslash is a literal character. - - ## List of available fragments Fragments are logical sections for the default prompt. They are accessible the same way as @@ -221,4 +192,35 @@ You can hover any used fragment and click `Insert` in the tooltip window. This w Rendered prompts can contain system text placeholders, which signify non-text information. - `[[screenshot_*]]` signifies a place where the screenshot will be placed - - `[[output_valid_json]]` signifies that we want to force the model to return JSON. Some models support this, and some don't, so for the non-supporting one, this is just replaced with worded instructions. \ No newline at end of file + - `[[output_valid_json]]` signifies that we want to force the model to return JSON. Some models support this, and some don't, so for the non-supporting one, this is just replaced with worded instructions. + +## The escapeJson helper + +Helpers transform a value before it is inserted into the prompt. To use one, type it right after +`{{` and pass the variable as its argument: + +```handlebars +{{escapeJson key.description}} +``` + +`escapeJson` escapes quotes, newlines and backslashes, so the value can be safely embedded inside a +JSON string. + +Most models are happy with a plain prose prompt, so you rarely need this. It becomes useful when you +send the prompt to a model or a service that expects a structured payload, and when you want to keep +a value from breaking out of the string that holds it — a key description ending with a quote could +otherwise be read as instructions rather than as data, which is one way prompt injection happens. + +```handlebars +{ + "context": "{{escapeJson key.name}} {{escapeJson key.description}}", + "text": "{{escapeJson source.translation}}", + "locale": "{{target.languageTag}}" +} +``` + +`escapeJson` is safe to use on any variable — applying it to a value that is already escaped returns +the value unchanged, so it never escapes twice. + +The result is escaped for a JSON string. It is also valid inside a **double-quoted** YAML scalar, but +not inside single-quoted, plain or block scalars, where a backslash is a literal character. \ No newline at end of file