docs(STRINGS-3096): Document upload file_format and async state contract - #1258
docs(STRINGS-3096): Document upload file_format and async state contract#1258Łukasz Ciesielski (lookasc) wants to merge 1 commit into
Conversation
…NGS-3096)
Clarify the POST /projects/{project_id}/uploads behavior:
- file_format is optional and auto-detected when omitted; recommend
omitting it rather than guessing, and note a provided value must match
the file's actual content (not just the project main format).
- Document the async contract: 201 on enqueue, poll the upload state
field, where state:error signals a processing/parse failure.
- Describe the upload state values (initialized, processing, success,
error) and point the show endpoint at the poll workflow.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
API changelog (oasdiff)Doc-only edits (descriptions, examples) do not appear here. |
Łukasz Ciesielski (lookasc)
changed the title
| file_format: | ||
| description: File format. Auto-detected when possible and not specified. | ||
| description: | | ||
| File format of the uploaded file (e.g. `json`, `simple_json`, `yml`). Optional — when omitted, the format is auto-detected from the file's content. We recommend omitting this parameter and letting auto-detection handle it rather than guessing. |
There was a problem hiding this comment.
where does this recommendation come from? how do we detect e.g. different json formats?
There was a problem hiding this comment.
jablan It is just a rewrite of what we had previously and my (incorrect) assumption based on what we use in the code FormatGuesser.guess_format.
I have just looked into its internals and know it is wrong for JSON formats.
What do you think to put it this way?
File format of the uploaded file, given as a format's `api_name` When omitted, Phrase attempts o auto-detect the format from the file's extension and content. Auto-detection is reliable only for formats with a distinctive extension or structure (e.g. `yml`, `xliff`, `csv`, `xml`, `strings`). It cannot disambiguate families that share an extension — in particular the JSON formats (`json`, `simple_json`, `nested_json`, `react_simple_json`, `go_i18n`, ...) all use `.json` and differ only in structure. For those, set `file_format` explicitly; otherwise the upload may be parsed as the wrong format or rejected as ambiguous. A provided `file_format` must match the actual content of the uploaded file, not merely the project's main format. A mismatch makes the upload fail.
There was a problem hiding this comment.
I don't think we should advise to omit this, on the contrary. I wouldn't clarify the auto detection beyond what's currently there. Also, the clarification about the project's main format seems too much, but obviously someone had problems with that. 🤷
Perhaps we should also point to the list of supported formats: https://support.phrase.com/hc/en-us/articles/9652464547740-Supported-File-Formats-Strings, although that page doesn't list the format identifiers which should be used here.
2 participants
Purpose
POST /projects/{project_id}/uploadsendpoint'sfile_formatparameter behaves, so API callers (including automated agents) stop guessing a format and silently failing.file_formatis optional: when omitted, Phrase auto-detects the format from the file's content, which is the recommended approach.file_formatmust match the uploaded file's actual content, not just the project's main format — a mismatch makes the upload fail.201once the file is accepted, and callers should poll the upload'sstatefield, whereerrorsignals a processing or parsing failure.statevalues so callers know what to expect while polling.Documentation only — no schema types, required fields, or endpoint behavior change.
Related ticket: https://phrase.atlassian.net/browse/STRINGS-3096