Merge pull request #463 from DeepL/docs/json-placeholders-option

docs(document): document json-placeholders conversion option and default placeholder protection

Author: yoshiamakino

api-reference/openapi.json

@@ -1191,7 +1191,7 @@
                     "description": "File extension of desired format of translated file, for example: `docx`. If unspecified, by default the translated file will be in the same format as the input file.\n"
                   },
                   "input_conversion_options": {
-                    "description": "Comma-separated list of `key:value` conversion options, prefixed with a version, that control how the input document is converted before translation. For example: `version:1,suppress-image-types:all`.\n\nSupported keys:\n\n  * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`.\n\nOnly `pptx` documents support conversion options; for other file types this parameter is ignored. Unrecognized keys are ignored.",
+                    "description": "Comma-separated list of `key:value` conversion options, prefixed with a version, that control how the input document is converted before translation. For example: `version:1,suppress-image-types:all`.\n\nSupported keys:\n\n  * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`. Only `pptx` documents support this key.\n  * `json-placeholders` - Controls how brace-delimited placeholders in `json` string values are handled. `protect` (the default) keeps identifier-shaped placeholders such as `{stars}` or `{{userName}}` verbatim so they are not translated; `translate` translates them along with the surrounding text. ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected, with only the branch text translated, in both modes. Multi-word groups such as `{see note}` are treated as translatable text in both modes.\n\nFor other file types this parameter is ignored. Unrecognized keys are ignored.",
                     "type": "string",
                     "example": "version:1,suppress-image-types:all"
                   },

api-reference/openapi.yaml

@@ -989,9 +989,10 @@ paths:
 
                     Supported keys:
 
-                      * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`.
+                      * `suppress-image-types` - Leaves the specified types of images embedded in the document untranslated. The value is a hyphen-separated list of image content types (for example `logo-photo` suppresses logos and photos), or `all` to suppress every embedded image. Recognized image content types: `logo`, `icon`, `decorative`, `barcode`, `formula`, `signature`, `handwriting`, `stamp`, `screenshot`, `diagram`, `chart`, `photo`, `illustration`, `comic`, `music`, `infographic`, `table`, `text`, `other`, `unknown`. Only `pptx` documents support this key.
+                      * `json-placeholders` - Controls how brace-delimited placeholders in `json` string values are handled. `protect` (the default) keeps identifier-shaped placeholders such as `{stars}` or `{{userName}}` verbatim so they are not translated; `translate` translates them along with the surrounding text. ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected, with only the branch text translated, in both modes. Multi-word groups such as `{see note}` are treated as translatable text in both modes.
 
-                    Only `pptx` documents support conversion options; for other file types this parameter is ignored. Unrecognized keys are ignored.
+                    For other file types this parameter is ignored. Unrecognized keys are ignored.
                   type: string
                   example: version:1,suppress-image-types:all
                 formality:

docs/best-practices/document-translations.mdx

@@ -58,6 +58,8 @@ Each supported format has behaviors and constraints worth knowing before you upl
 - Files must be strict, parseable JSON — no trailing commas, no comments. JSONC-style extensions are not supported.
 - **Upload limit is 1 MB** regardless of plan. Large metadata payloads (e.g., DataCite, Zenodo, Backstage catalog dumps) may need to be split, or translated string-by-string via the text-translation API.
 - Embedded HTML or Markdown inside string values (common in Contentful Rich Text and similar CMS payloads) is handled — DeepL translates the natural-language text and attempts to preserve the embedded markup. Review the output for complex rich-text content.
+- Brace-delimited placeholders such as `{stars}` or `{{userName}}` are kept verbatim by default, so template variables survive translation. Multi-word groups such as `{see note}` are treated as translatable text. To translate placeholders along with the text, set `input_conversion_options=version:1,json-placeholders:translate` when uploading.
+- ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected: the variable name, keywords, and categories stay intact while the branch text is translated. Branch text is translated in isolation, so review plural forms in the output. Languages whose plural categories are absent from the source (for example Polish `few`/`many` from an English message) fall back to `other`. Expand categories in your i18n tooling if exact pluralization matters.
 - To protect specific values from translation, encode them as non-strings (numbers/booleans/null) or pre-process the file to strip them.
 
 **IDML**

docs/resources/roadmap-and-release-notes.mdx

@@ -9,6 +9,10 @@ rss: true
 </Update>
 
 <Update label="September 2026">
+## September 30 - JSON Placeholder Protection
+- [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) protects brace-delimited placeholders in `json` documents by default: values such as `{stars}` or `{{userName}}` are kept verbatim instead of being translated along with the surrounding text. Set `input_conversion_options=version:1,json-placeholders:translate` to translate them instead.
+- ICU MessageFormat skeletons such as `{count, plural, one {# item} other {# items}}` are always protected, with only the branch text translated, in both modes.
+
 ## September 29 - New Document Formats (Beta) and Embedded Image Translation Controls
 - [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now supports ten additional file formats, all currently in beta: `xlsm` (macro-enabled Excel), `zip` (SCORM e-learning packages), `vtt` (WebVTT subtitles), `yaml` / `yml`, `properties` (Java properties), `strings` (iOS/macOS strings), `md` / `markdown`, `resx` (.NET resources), `odt` (OpenDocument Text), and `rtf` (Rich Text Format).
 - A new `input_conversion_options` parameter controls how the input document is converted before translation. The `suppress-image-types` option leaves specified types of images embedded in `pptx` documents untranslated. For example, `version:1,suppress-image-types:all` suppresses all embedded images, and `version:1,suppress-image-types:logo-photo` suppresses logos and photos only.