Skip to content

Error message wording has no convention: terminal punctuation, phrasing, and value quoting all vary #677

Description

@smunini

Summary

Error message wording has no house style. Full-sentence errors end with a period in some places and not in others, the same failure is phrased two different ways in the same file, and the grammatical shape swings between "Could not load X", "X failed", and "The request failed". Pick a convention, write it into crates/ui/README.md next to the existing capitalization rules, and sweep the catalogs and the server error strings.

Current behavior

Terminal punctuation is split roughly down the middle in locales/en/main.ftl. Full-sentence errors with a period:

83:  error-not-found = The requested resource was not found.
84:  error-unauthorized = You are not authorized to perform this action.
85:  error-generic = Something went wrong. Please try again.
197: history-load-error = Could not load that resource's history.
208: history-parse-error = Those versions could not be read as JSON.
468: editor-load-error = Could not load that resource.
513: resources-save-invalid = The JSON is not valid — fix it before saving.

Full-sentence errors without one:

529: batch-invalid-json = That file is not valid JSON
530: batch-not-a-bundle = That JSON is not a FHIR Bundle
531: batch-bad-type = Only Bundles of type batch or transaction can be executed here
547: batch-request-failed = The request failed
63:  terminology-invalid-heading = HFS_TERMINOLOGY_SERVER is invalid

Grammatical shape varies for the same class of failure. Could not load that resource. (468) vs Delete failed (288) vs Provisioning failed (136) vs The request failed (547). Some name the object, some name the operation, some name neither.

error-generic is the only string that says "Please" (85: Something went wrong. Please try again.), which sets a register nothing else in the catalog matches.

Server-side error text disagrees with itself inside one file. crates/rest/src/error.rs phrases the same conditions two ways — the Display impl uses Label: value, the OperationOutcome diagnostics use a natural sentence:

Condition Display OperationOutcome diagnostics
Not found :255 Resource not found: {}/{} :360 Resource {}/{} not found
Version not found :267 Version not found: {}/{}/_history/{} :375 Version {} of {}/{} not found
Conditional match :280 Multiple matches ({}) for conditional {} :389 Conditional {} matched {} resources, expected at most 1
Media type :288 Unsupported media type: {} :399 Content type '{}' is not supported

These diagnostics reach the user verbatim — the Batch / Transaction page renders issue[0].diagnostics straight into the page (crates/ui/assets/batch.js:222-225), as does the search builder (crates/ui/assets/saved-queries.js:2034-2038). So server phrasing and UI phrasing sit side by side in the same error line.

Value quoting is inconsistentContent type '{}' is not supported and Invalid parameter '{}': {} single-quote the offending value; Resource not found: {}/{} and Unsupported media type: {} do not.

Expected behavior

One documented convention for error text, applied everywhere:

  • A decision on terminal punctuation for full sentences (and the rule that short fragments and status values take none).
  • One grammatical shape for operation failures, so Delete failed / Provisioning failed / The request failed / Could not load that resource all follow the same pattern.
  • One rule for quoting interpolated values.
  • Server Display text and OperationOutcome diagnostics for the same condition agree.
  • The convention written down in crates/ui/README.md under the existing "Copy capitalization (UI copy: no capitalization convention — headings and buttons mix Title Case and sentence case #652)" section, which already fixes sentence case for error messages but says nothing about punctuation or phrasing.

Evidence

  • crates/ui/README.md:119-137 — the existing copy convention; covers capitalization only
  • locales/en/main.ftl:83-85, :136, :197, :208, :288, :468, :513, :529-531, :547 — the strings quoted above
  • crates/rest/src/error.rs:255-288 vs :360-399Display vs diagnostics for the same conditions
  • crates/ui/assets/batch.js:222-225, crates/ui/assets/saved-queries.js:2034-2038 — server diagnostics surfaced verbatim in the UI
  • locales/de/main.ftl, locales/es/main.ftl — parallel catalogs that need the same sweep

Suggested approach

  1. Write the convention into crates/ui/README.md alongside the capitalization rules. A workable starting point: full sentences take a terminal period; fragments, labels, and status values take none; operation failures use a consistent shape; interpolated values are single-quoted.
  2. Sweep locales/en/main.ftl, then mirror into de and es. The Fluent keys do not change, only the values, so no template or JS edits are needed for this part.
  3. Reconcile crates/rest/src/error.rs so Display and the OperationOutcome diagnostics tell the same story per variant; the assertions at :903 and :937 will need updating.
  4. Consider a test that asserts the punctuation rule over the en catalog so new strings do not drift back.

Scope / out of scope

Error message text only. Visual treatment and placement of errors are tracked separately in #676. Capitalization is already settled by #652 — this issue does not revisit it. Log messages and tracing output are out of scope; only text a user can see.

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingui

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions