From e31bd6532cd6a297388dc48447aec22dea57ec4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Ciesielski?= Date: Thu, 3 Sep 2026 07:01:37 +0000 Subject: [PATCH 1/2] docs(STRINGS-3041): document supported placeholder_styles values Add an enum of supported placeholder style keys for the placeholder_styles field on projects (create/update/response schemas), so API clients can discover valid values instead of guessing. --- doc/compiled.json | 48 ++++++++++++++++++++++++++-------- paths/projects/create.yaml | 6 ++--- paths/projects/update.yaml | 6 ++--- schemas.yaml | 2 ++ schemas/placeholder_style.yaml | 27 +++++++++++++++++++ schemas/project_details.yaml | 10 +++---- 6 files changed, 77 insertions(+), 22 deletions(-) create mode 100644 schemas/placeholder_style.yaml diff --git a/doc/compiled.json b/doc/compiled.json index e2f2d2213..960f04989 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -808,6 +808,32 @@ ], "example": "string" }, + "placeholder_style": { + "type": "string", + "description": "Placeholder style supported for detecting and highlighting variable placeholders in translation keys.", + "enum": [ + "rails_i18n", + "i18next_nesting", + "gettext_python", + "cstyle", + "python_strings", + "dot_net", + "java_properties", + "laravel", + "square_brackets", + "single_percentage", + "double_percentage", + "emoji", + "dollar_style", + "nsis", + "razor", + "double_curly", + "xliffg", + "xliff", + "liquid" + ], + "example": "rails_i18n" + }, "key_preview": { "type": "object", "title": "key_preview", @@ -2320,11 +2346,11 @@ "placeholder_styles": { "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/placeholder_style" }, "example": [ - "angular", - "iOS" + "rails_i18n", + "java_properties" ] }, "branch": { @@ -2353,8 +2379,8 @@ "cldr_version": "legacy", "job_locking_enabled": false, "placeholder_styles": [ - "angular", - "iOS" + "rails_i18n", + "java_properties" ] } } @@ -18006,11 +18032,11 @@ "description": "(Optional) List of placeholder styles enabled for the project.", "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/placeholder_style" }, "example": [ - "angular", - "iOS" + "rails_i18n", + "java_properties" ] } } @@ -18315,11 +18341,11 @@ "description": "(Optional) List of placeholder styles enabled for the project.", "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/placeholder_style" }, "example": [ - "angular", - "iOS" + "rails_i18n", + "java_properties" ] }, "autocomplete_job_enabled": { diff --git a/paths/projects/create.yaml b/paths/projects/create.yaml index 4e671a6f2..2bc635f3d 100644 --- a/paths/projects/create.yaml +++ b/paths/projects/create.yaml @@ -217,8 +217,8 @@ requestBody: description: "(Optional) List of placeholder styles enabled for the project." type: array items: - type: string + "$ref": "../../schemas/placeholder_style.yaml#/placeholder_style" example: - - "angular" - - "iOS" + - "rails_i18n" + - "java_properties" x-cli-version: "2.6.3" diff --git a/paths/projects/update.yaml b/paths/projects/update.yaml index 552c46f3f..f9606dfa2 100644 --- a/paths/projects/update.yaml +++ b/paths/projects/update.yaml @@ -181,10 +181,10 @@ requestBody: description: "(Optional) List of placeholder styles enabled for the project." type: array items: - type: string + "$ref": "../../schemas/placeholder_style.yaml#/placeholder_style" example: - - "angular" - - "iOS" + - "rails_i18n" + - "java_properties" autocomplete_job_enabled: description: "(Optional) Enable autocomplete-job behavior so that newly created keys and locales are automatically added to in-progress jobs." type: boolean diff --git a/schemas.yaml b/schemas.yaml index a1584bf05..6363d9427 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -20,6 +20,8 @@ schemas: "$ref": schemas/custom_metadata_property.yaml#/custom_metadata_property custom_metadata_data_type: "$ref": schemas/custom_metadata_data_type.yaml#/data_type + placeholder_style: + "$ref": schemas/placeholder_style.yaml#/placeholder_style key_preview: "$ref": schemas/key_preview.yaml#/key_preview affected_count: diff --git a/schemas/placeholder_style.yaml b/schemas/placeholder_style.yaml new file mode 100644 index 000000000..07bd3af63 --- /dev/null +++ b/schemas/placeholder_style.yaml @@ -0,0 +1,27 @@ +--- +placeholder_style: + type: string + description: >- + Placeholder style supported for detecting and highlighting variable + placeholders in translation keys. + enum: + - rails_i18n + - i18next_nesting + - gettext_python + - cstyle + - python_strings + - dot_net + - java_properties + - laravel + - square_brackets + - single_percentage + - double_percentage + - emoji + - dollar_style + - nsis + - razor + - double_curly + - xliffg + - xliff + - liquid + example: rails_i18n diff --git a/schemas/project_details.yaml b/schemas/project_details.yaml index e72afd129..33a872762 100644 --- a/schemas/project_details.yaml +++ b/schemas/project_details.yaml @@ -66,10 +66,10 @@ project_details: placeholder_styles: type: array items: - type: string + "$ref": "./placeholder_style.yaml#/placeholder_style" example: - - "angular" - - "iOS" + - "rails_i18n" + - "java_properties" branch: "$ref": "./branch.yaml#/branch" @@ -95,5 +95,5 @@ project_details: cldr_version: "legacy" job_locking_enabled: false placeholder_styles: - - "angular" - - "iOS" + - "rails_i18n" + - "java_properties" From 8ce2e81e3f6f1abe3716d8b272090a30f804fcae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Ciesielski?= Date: Thu, 3 Sep 2026 07:12:57 +0000 Subject: [PATCH 2/2] docs(STRINGS-3041): use x-extensible-enum for placeholder_styles A plain enum flags the property as newly type-constrained from the API consumer's perspective, which the breaking-change check treats as a breaking change on the request side, and any future style addition would flag as breaking on the response side. Document the known values via x-extensible-enum instead, which supports listing/growing known values without breaking existing or future clients. --- doc/compiled.json | 4 ++-- schemas/placeholder_style.yaml | 5 +++-- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 960f04989..19501d9d6 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -810,8 +810,8 @@ }, "placeholder_style": { "type": "string", - "description": "Placeholder style supported for detecting and highlighting variable placeholders in translation keys.", - "enum": [ + "description": "Placeholder style supported for detecting and highlighting variable placeholders in translation keys. This list may grow over time as new styles are added.", + "x-extensible-enum": [ "rails_i18n", "i18next_nesting", "gettext_python", diff --git a/schemas/placeholder_style.yaml b/schemas/placeholder_style.yaml index 07bd3af63..e7deb1434 100644 --- a/schemas/placeholder_style.yaml +++ b/schemas/placeholder_style.yaml @@ -3,8 +3,9 @@ placeholder_style: type: string description: >- Placeholder style supported for detecting and highlighting variable - placeholders in translation keys. - enum: + placeholders in translation keys. This list may grow over time as new + styles are added. + x-extensible-enum: - rails_i18n - i18next_nesting - gettext_python