Skip to content

fix(API): make translation content and key description nullable #STRINGS-3652 #1325

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Mikko Karkee (Varpuspaavi) wants to merge 5 commits into
base: main
Choose a base branch
from
Open

fix(API): make translation content and key description nullable #STRINGS-3652 #1325

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e19014b
fix(API): make translation update content/branch/plural_suffix nullab…
Varpuspaavi Oct 15, 2026
1382b16
docs(API): drop null claim from translation update content descriptio…
Varpuspaavi Oct 15, 2026
bea5c33
fix(API): make key update description nullable #STRINGS-3652
Varpuspaavi Oct 15, 2026
f3dd548
docs(API): note CLI drops null for nullable update fields #STRINGS-3652
Varpuspaavi Oct 19, 2026
4a610f9
fix(API): limit nullable to translation content and key description #…
Varpuspaavi Oct 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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..."
},
"plural": {
Expand Down Expand Up @@ -28705,8 +28706,9 @@
"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. The Phrase CLI drops `null` values before sending, so use an empty string there.",
"type": "string",
"nullable": true,
"example": "My translation"
},
"plural_suffix": {
Expand Down
3 changes: 2 additions & 1 deletion paths/keys/update.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 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...
plural:
description: Indicates whether key supports pluralization
Expand Down
3 changes: 2 additions & 1 deletion paths/translations/update.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,8 +63,9 @@ requestBody:
type: string
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. The Phrase CLI drops `null` values before sending, so use an empty string there.
type: string
nullable: true

@bikmazefe Efe Bikmaz (bikmazefe) Oct 16, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nullable: true advertises null as a valid value, but the description tells callers to send an empty string, and the PR notes {"content":null} is still dropped by the CLI. The spec, the prose and the CLI behaviour disagree: generated clients will accept null, while the CLI silently ignores it. Consider either documenting the null semantics (and the CLI limitation) or rewording the description so it doesn't imply null is unsupported.

@Varpuspaavi Mikko Karkee (Varpuspaavi) Oct 19, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, fair point. Checking the API code showed null clears content and description, so the descriptions now say an empty string or null clears the value, and that the CLI drops null (use "" there). I also removed nullable from branch and plural_suffix: branch is only a selector (null is ignored) and plural_suffix is NOT NULL in the DB. Pushed in 4a610f9. Note the null behavior comes from reading the API code, not from running requests.

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.'
Expand Down
Loading