From 120eab3aa1b3eb5fb7fd47388f496558cedc68cc Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Wed, 30 Sep 2026 10:35:27 +0100 Subject: [PATCH 1/2] docs(document): document json-placeholders conversion option and default placeholder protection --- api-reference/openapi.json | 2 +- api-reference/openapi.yaml | 5 +++-- docs/best-practices/document-translations.mdx | 2 ++ docs/resources/roadmap-and-release-notes.mdx | 4 ++++ 4 files changed, 10 insertions(+), 3 deletions(-) diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 539f2c13..927dbe09 100644 --- a/api-reference/openapi.json +++ b/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" }, diff --git a/api-reference/openapi.yaml b/api-reference/openapi.yaml index de409c1b..24f33dba 100644 --- a/api-reference/openapi.yaml +++ b/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: diff --git a/docs/best-practices/document-translations.mdx b/docs/best-practices/document-translations.mdx index 20b5b489..33671926 100644 --- a/docs/best-practices/document-translations.mdx +++ b/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** diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 6659b8ad..256f9c8a 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -9,6 +9,10 @@ rss: true +## September 30 - JSON Placeholder Protection +- [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now 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. From 4d5a97adf1fbc23117fcb0279d768c81bbde632e Mon Sep 17 00:00:00 2001 From: Yoshia Makino Date: Wed, 30 Sep 2026 10:40:04 +0100 Subject: [PATCH 2/2] docs(changelog): drop 'now' from JSON placeholder protection entry --- docs/resources/roadmap-and-release-notes.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resources/roadmap-and-release-notes.mdx b/docs/resources/roadmap-and-release-notes.mdx index 256f9c8a..825ef02b 100644 --- a/docs/resources/roadmap-and-release-notes.mdx +++ b/docs/resources/roadmap-and-release-notes.mdx @@ -10,7 +10,7 @@ rss: true ## September 30 - JSON Placeholder Protection -- [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document) now 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. +- [`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