From e19014b5f3044b019a498d7b914924f5ff77944d Mon Sep 17 00:00:00 2001 From: Varpuspaavi Date: Thu, 15 Oct 2026 15:25:58 +0200 Subject: [PATCH 1/5] fix(API): make translation update content/branch/plural_suffix nullable #STRINGS-3652 Plain string fields generate Go structs with omitempty, so the CLI dropped {"content":""} before sending and clearing a translation silently no-op'd. Marking them nullable generates *NullableString, which preserves an empty string on the wire. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 5 ++++- paths/translations/update.yaml | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 0fb70590f..08b924f0f 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -28702,16 +28702,19 @@ "branch": { "description": "specify the branch to use", "type": "string", + "nullable": true, "example": "my-feature-branch" }, "content": { - "description": "Translation content", + "description": "Translation content. Send an empty string or `null` to clear the translation's content; omit the field to leave it unchanged.", "type": "string", + "nullable": true, "example": "My translation" }, "plural_suffix": { "description": "Plural suffix. Can be one of: zero, one, two, few, many, other. Must be specified if the key associated to the translation is pluralized.", "type": "string", + "nullable": true, "example": null }, "unverified": { diff --git a/paths/translations/update.yaml b/paths/translations/update.yaml index 57b2a5816..bd68f1c7e 100644 --- a/paths/translations/update.yaml +++ b/paths/translations/update.yaml @@ -61,14 +61,17 @@ requestBody: branch: description: specify the branch to use type: string + nullable: true example: my-feature-branch content: - description: Translation content + description: Translation content. Send an empty string or `null` to clear the translation's content; omit the field to leave it unchanged. type: string + nullable: true example: My translation plural_suffix: description: 'Plural suffix. Can be one of: zero, one, two, few, many, other. Must be specified if the key associated to the translation is pluralized.' type: string + nullable: true example: unverified: description: Indicates whether translation is unverified. Part of the [Advanced Workflows](https://support.phrase.com/hc/en-us/articles/5784094755484) feature. From 1382b16afcbc568aa9b793ba3db002c70650bdc2 Mon Sep 17 00:00:00 2001 From: Varpuspaavi Date: Thu, 15 Oct 2026 15:29:54 +0200 Subject: [PATCH 2/5] docs(API): drop null claim from translation update content description #STRINGS-3652 The CLI and Go client still drop {"content":null}; only document the empty string as the way to clear content. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 2 +- paths/translations/update.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 08b924f0f..e986203cd 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -28706,7 +28706,7 @@ "example": "my-feature-branch" }, "content": { - "description": "Translation content. Send an empty string or `null` to clear the translation's content; omit the field to leave it unchanged.", + "description": "Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged.", "type": "string", "nullable": true, "example": "My translation" diff --git a/paths/translations/update.yaml b/paths/translations/update.yaml index bd68f1c7e..11c26b1ff 100644 --- a/paths/translations/update.yaml +++ b/paths/translations/update.yaml @@ -64,7 +64,7 @@ requestBody: nullable: true example: my-feature-branch content: - description: Translation content. Send an empty string or `null` to clear the translation's content; omit the field to leave it unchanged. + description: Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged. type: string nullable: true example: My translation From bea5c33639db162b66244547912424f4a332a304 Mon Sep 17 00:00:00 2001 From: Varpuspaavi Date: Thu, 15 Oct 2026 15:31:55 +0200 Subject: [PATCH 3/5] fix(API): make key update description nullable #STRINGS-3652 Same omitempty issue as translation update: an empty description was dropped client-side, so clearing a key description silently no-op'd. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 3 ++- paths/keys/update.yaml | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index e986203cd..e80fc7ac7 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -24608,8 +24608,9 @@ "example": "home.index.headline" }, "description": { - "description": "Key description (usually includes contextual information for translators)", + "description": "Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged.", "type": "string", + "nullable": true, "example": "Some description worth knowing..." }, "plural": { diff --git a/paths/keys/update.yaml b/paths/keys/update.yaml index ae8ce1a98..bd54b68f6 100644 --- a/paths/keys/update.yaml +++ b/paths/keys/update.yaml @@ -74,8 +74,9 @@ requestBody: type: string example: home.index.headline description: - description: Key description (usually includes contextual information for translators) + description: Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged. type: string + nullable: true example: Some description worth knowing... plural: description: Indicates whether key supports pluralization From f3dd5485dd48adde725b39251a3b8eda97032717 Mon Sep 17 00:00:00 2001 From: Varpuspaavi Date: Mon, 19 Oct 2026 12:06:10 +0200 Subject: [PATCH 4/5] docs(API): note CLI drops null for nullable update fields #STRINGS-3652 Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 4 ++-- paths/keys/update.yaml | 2 +- paths/translations/update.yaml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index e80fc7ac7..247e96999 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -24608,7 +24608,7 @@ "example": "home.index.headline" }, "description": { - "description": "Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged.", + "description": "Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending.", "type": "string", "nullable": true, "example": "Some description worth knowing..." @@ -28707,7 +28707,7 @@ "example": "my-feature-branch" }, "content": { - "description": "Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged.", + "description": "Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending.", "type": "string", "nullable": true, "example": "My translation" diff --git a/paths/keys/update.yaml b/paths/keys/update.yaml index bd54b68f6..0fd3fa654 100644 --- a/paths/keys/update.yaml +++ b/paths/keys/update.yaml @@ -74,7 +74,7 @@ requestBody: type: string example: home.index.headline description: - description: Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged. + description: Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending. type: string nullable: true example: Some description worth knowing... diff --git a/paths/translations/update.yaml b/paths/translations/update.yaml index 11c26b1ff..61dcc3aa0 100644 --- a/paths/translations/update.yaml +++ b/paths/translations/update.yaml @@ -64,7 +64,7 @@ requestBody: nullable: true example: my-feature-branch content: - description: Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged. + description: Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending. type: string nullable: true example: My translation From 4a610f9ffbea9605881bd38582f7d30b4d4bd81e Mon Sep 17 00:00:00 2001 From: Varpuspaavi Date: Mon, 19 Oct 2026 12:17:00 +0200 Subject: [PATCH 5/5] fix(API): limit nullable to translation content and key description #STRINGS-3652 branch is ignored when null and plural_suffix is NOT NULL in the DB, so neither should be advertised as nullable. Co-Authored-By: Claude Sonnet 5.5 --- doc/compiled.json | 6 ++---- paths/keys/update.yaml | 2 +- paths/translations/update.yaml | 4 +--- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 247e96999..af2abb6a3 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -24608,7 +24608,7 @@ "example": "home.index.headline" }, "description": { - "description": "Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending.", + "description": "Key description (usually includes contextual information for translators). Send an empty string or `null` to clear the description; omit the field to leave it unchanged. The Phrase CLI drops `null` values before sending, so use an empty string there.", "type": "string", "nullable": true, "example": "Some description worth knowing..." @@ -28703,11 +28703,10 @@ "branch": { "description": "specify the branch to use", "type": "string", - "nullable": true, "example": "my-feature-branch" }, "content": { - "description": "Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending.", + "description": "Translation content. Send an empty string or `null` to clear the translation's content; omit the field to leave it unchanged. The Phrase CLI drops `null` values before sending, so use an empty string there.", "type": "string", "nullable": true, "example": "My translation" @@ -28715,7 +28714,6 @@ "plural_suffix": { "description": "Plural suffix. Can be one of: zero, one, two, few, many, other. Must be specified if the key associated to the translation is pluralized.", "type": "string", - "nullable": true, "example": null }, "unverified": { diff --git a/paths/keys/update.yaml b/paths/keys/update.yaml index 0fd3fa654..70129451e 100644 --- a/paths/keys/update.yaml +++ b/paths/keys/update.yaml @@ -74,7 +74,7 @@ requestBody: type: string example: home.index.headline description: - description: Key description (usually includes contextual information for translators). Send an empty string to clear the description; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending. + description: Key description (usually includes contextual information for translators). Send an empty string or `null` to clear the description; omit the field to leave it unchanged. The Phrase CLI drops `null` values before sending, so use an empty string there. type: string nullable: true example: Some description worth knowing... diff --git a/paths/translations/update.yaml b/paths/translations/update.yaml index 61dcc3aa0..dc3ce01e5 100644 --- a/paths/translations/update.yaml +++ b/paths/translations/update.yaml @@ -61,17 +61,15 @@ requestBody: branch: description: specify the branch to use type: string - nullable: true example: my-feature-branch content: - description: Translation content. Send an empty string to clear the translation's content; omit the field to leave it unchanged. Prefer an empty string over `null`; the Phrase CLI drops `null` values before sending. + description: Translation content. Send an empty string or `null` to clear the translation's content; omit the field to leave it unchanged. The Phrase CLI drops `null` values before sending, so use an empty string there. type: string nullable: true example: My translation plural_suffix: description: 'Plural suffix. Can be one of: zero, one, two, few, many, other. Must be specified if the key associated to the translation is pluralized.' type: string - nullable: true example: unverified: description: Indicates whether translation is unverified. Part of the [Advanced Workflows](https://support.phrase.com/hc/en-us/articles/5784094755484) feature.