fix(API): make translation update content/branch/plural_suffix nullable #STRINGS-3652

[Mikko Karkee (Varpuspaavi)]

Problem

STRINGS-3652: phrase translations update --data '{"content":""}' returns success but leaves the translation unchanged. The same payload sent directly to the API clears it.

content, branch and plural_suffix on translation/update were plain type: string, so the generated Go model uses string with json:",omitempty". The CLI unmarshals --data into that struct and re-marshals it, and omitempty drops "", so the key never reaches the API.

Change

• paths/translations/update.yaml: mark branch, content, plural_suffix as nullable: true; document that an empty string clears content and omitting it leaves it unchanged (null deliberately not documented, see limitation below).
• paths/keys/update.yaml: mark description as nullable: true (same omitempty bug; empty string now clears it).
• doc/compiled.json: regenerated (make bundle).

Generated Go model now uses *NullableString (same pattern as repo_sync name). clients/ is gitignored and regenerated on release.

Verification

Ran make go and a throwaway marshal round-trip on the generated model:

Input	Output
{"content":""}	{"content":""}
{"content":"x"}	{"content":"x"}
{}	{}
{"content":null}	{}

swagger-cli validate main.yaml passes. Other language generators were not run.

Known limitation (out of scope)

{"content":null} through the CLI is still dropped: encoding/json sets a *NullableString to nil on JSON null without calling UnmarshalJSON. Fixing it needs a Go model template change affecting all nullable fields, so it is deliberately not done here. Direct API calls with null are unaffected.

Follow-up

Once released, phrase-cli needs a phrase-go dependency bump to pick this up.

🤖 Generated with Claude Code

[github-actions]

API changelog (oasdiff)

Doc-only edits (descriptions, examples) do not appear here.

4 changes: 0 error, 0 warning, 4 info
info	[request-property-became-nullable] at doc/compiled.json
	in API PATCH /projects/{project_id}/keys/{id}
		the request property `description` became nullable

info	[request-property-became-nullable] at doc/compiled.json
	in API PATCH /projects/{project_id}/translations/{id}
		the request property `branch` became nullable

info	[request-property-became-nullable] at doc/compiled.json
	in API PATCH /projects/{project_id}/translations/{id}
		the request property `content` became nullable

info	[request-property-became-nullable] at doc/compiled.json
	in API PATCH /projects/{project_id}/translations/{id}
		the request property `plural_suffix` became nullable

[Efe Bikmaz (bikmazefe)]

Two review notes on the nullable change.

[Efe Bikmaz (bikmazefe)]

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.

[Efe Bikmaz (bikmazefe)]

This changes the generated Go model type for branch, content and plural_suffix (and description in keys update) from string to *NullableString. That is source-breaking for typed phrase-go consumers, e.g. body.Content = "x" stops compiling, and other typed clients (Java, Swift, TypeScript) change field types too. oasdiff only reports it as info. Could the PR description call this out and say what release/version bump it needs?