Write draft translation

PUT

/api/v1/applications/{applicationId}/keys/{messageKey}/translations/{locale}

Sets the draft text of the key in the locale. The text must be valid ICU and may only use the arguments of the key, with a compatible type; otherwise the response is 400 with the offending argument. The draft is published with the next release.

Authorizations

• bearerAuth
  stx-i18n:translation-update

Parameters

Path Parameters

applicationId

required

Lowercase slug that identifies an application

string

/^[a-z][a-z0-9-]{1,62}$/

Identifier of the application, a lowercase slug chosen at creation (match-tracker). Consumer applications configure it, so it never changes.

messageKey

required

Dotted message key, as in the translation files of the application

string

<= 200 characters /^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/

Dotted message key (matchCreateCommand.gameId.label)

locale

required

BCP 47 language tag (language, optionally a script and a region)

string

/^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$/

BCP 47 language tag of the locale (nl, en-GB)

Header Parameters

Idempotency-Key

required

string

Client-generated UUIDv7, required on every mutating request (POST, PUT, PATCH, DELETE), that makes the request safe to retry. A repeated request with the same key and the same payload returns the stored response (marked with the Idempotent-Replayed: true header) instead of executing again; the same key with a different payload is refused with 422. Keys older than the retention window (30 days) are rejected. A key that is not a UUID is refused with 400.

If-Match

required

string

ETag of the resource being modified, for optimistic concurrency control: the request is refused with 412 when the resource changed since. Obtain it from the ETag response header of a previous GET or mutation.

Request Body^required

object

text

required

Text of a message in ICU MessageFormat: plain text, {name}, {n, number}, {d, date, short}, {n, plural, one {...} other {...}} and {x, select, a {...} other {...}}. It may only use the arguments of its key.

string

<= 4000 characters

Responses

200

Message key retrieved or changed successfully

A message key with its base text and the translation per locale

object

key

required

Dotted message key, as in the translation files of the application

string

<= 200 characters /^[A-Za-z0-9_]+(\.[A-Za-z0-9_]+)*$/

baseText

required

Text in the base locale, from the last import

string

<= 4000 characters

description

Context for translators, from the last import

string

arguments

required

Arguments a translation may use

Array<object>

object

name

required

string

/^[A-Za-z][A-Za-z0-9_]*$/

type

required

Type of a message argument: ANY (formatted with toString), NUMBER (number, plural and #), DATE (date and time), STRING (select).

string

Allowed values: ANY NUMBER DATE STRING

obsolete

required

The last import no longer contained this key. An obsolete key is not published.

boolean

translations

required

Array<object>

object

locale

required

BCP 47 language tag (language, optionally a script and a region)

string

/^[a-z]{2,3}(-[A-Z][a-z]{3})?(-([A-Z]{2}|[0-9]{3}))?$/

status

required

Status of a translation: MISSING (no text yet), DRAFT (a text that is not published), PUBLISHED (the published text, without a newer draft), CHANGED (published, with a newer draft).

string

Allowed values: MISSING DRAFT PUBLISHED CHANGED

draft

Text that is published with the next release; absent without a draft

string

<= 4000 characters

published

Text of the latest release; absent before the key is published

string

<= 4000 characters

updatedAt

Date-time (ISO 8601)

string format: date-time

updatedBy

object

id

required

string format: uuid

displayName

required

string

Headers

ETag

string

Current version of the resource; send it as If-Match to change or delete it

Idempotent-Replayed

string

Allowed values: true

Present (true) when the response was replayed from an earlier request with the same Idempotency-Key, instead of being executed again

400

Request validation failed

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

errors

Array<object>

object

field

required

Field or property that failed validation

string

code

required

Machine-readable validation error code, e.g. REQUIRED, VALUE_TOO_LONG, INVALID_FORMAT, OUT_OF_RANGE. Canonical list is maintained per resource in the documentation.

string

message

required

Human readable validation message

string

rejectedValue

The actual value that failed validation. Omitted if the value is sensitive.

Examples

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "Received invalid request data",
  "errors": [
    {
      "field": "displayName",
      "code": "REQUIRED",
      "message": "missing required field"
    }
  ]
}

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "Received invalid request data",
  "errors": [
    {
      "field": "participants[2].ghostPlayerId",
      "code": "DUPLICATE_GHOST_PLAYER",
      "message": "the ghost player already takes part in this match"
    }
  ]
}

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "query",
      "code": "INVALID_SEARCH",
      "message": "'nonsense' is not a filterable field"
    }
  ]
}

401

Authentication required or token invalid

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/authentication",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Authentication required"
}

403

Insufficient permissions

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/authorization",
  "title": "Access denied",
  "status": 403,
  "detail": "Insufficient permissions"
}

404

Resource not found

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/not-found",
  "title": "Resource not found",
  "status": 404,
  "detail": "The requested resource could not be found"
}

409

The requested mutation is not allowed in the resource’s current state, or it conflicts with existing data (a unique value that is already taken)

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/conflict",
  "title": "Already exists",
  "status": 409,
  "detail": "A game with source bgg:199792 already exists."
}

{
  "type": "https://errors.stratastax.dev/conflict",
  "title": "Self ghost player",
  "status": 409,
  "detail": "The ghost player that represents yourself cannot be deleted or unclaimed."
}

{
  "type": "https://errors.stratastax.dev/conflict",
  "title": "Match is finalized",
  "status": 409,
  "detail": "This match is FINALIZED; propose a change via POST /matches/{matchId}/edits instead."
}

412

The If-Match header did not match the current resource’s ETag

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/precondition-failed",
  "title": "Resource has changed",
  "status": 412,
  "detail": "The resource was modified since you last fetched it. Reload and try again."
}

422

The Idempotency-Key was already used for a request with a different payload

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

errors

Array<object>

object

field

required

Field or property that failed validation

string

code

required

Machine-readable validation error code, e.g. REQUIRED, VALUE_TOO_LONG, INVALID_FORMAT, OUT_OF_RANGE. Canonical list is maintained per resource in the documentation.

string

message

required

Human readable validation message

string

rejectedValue

The actual value that failed validation. Omitted if the value is sensitive.

Examples

{
  "type": "https://errors.stratastax.dev/validation",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Idempotency key reused for a different request",
  "errors": [
    {
      "field": "Idempotency-Key",
      "code": "IDEMPOTENCY_KEY_REUSED",
      "message": "0192f100-0000-7000-8000-0000000000a5 was already used for a different request"
    }
  ]
}

500

Unexpected server error

object

type

required

Canonical error type identifier (URI). The values are the problem types of stratastax-http’s problem-core; stratastax-codegen fails the build of a service when the two disagree.

string

Allowed values: https://errors.stratastax.dev/authentication https://errors.stratastax.dev/authorization https://errors.stratastax.dev/validation https://errors.stratastax.dev/not-found https://errors.stratastax.dev/conflict https://errors.stratastax.dev/precondition-failed https://errors.stratastax.dev/internal

title

required

Short, human-readable summary

string

status

required

HTTP status code

integer format: int32

detail

required

Human-readable explanation

string

instance

URI of the request that caused the error

string format: uri

Examples

{
  "type": "https://errors.stratastax.dev/internal",
  "title": "Oops! Something went wrong.",
  "status": 500,
  "detail": "Try again later."
}