From e6617ece0fdd14244ccb888eb58a92594ed5d830 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Behrendt?= Date: Fri, 24 Jul 2026 14:34:54 +0200 Subject: [PATCH 1/2] add pre_translations resource to API --- doc/compiled.json | 283 +++++++++++++++++++++++++++++ main.yaml | 1 + paths.yaml | 8 + paths/pre_translations/create.yaml | 67 +++++++ paths/pre_translations/index.yaml | 46 +++++ paths/pre_translations/show.yaml | 38 ++++ schemas.yaml | 2 + schemas/pre_translation.yaml | 40 ++++ 8 files changed, 485 insertions(+) create mode 100644 paths/pre_translations/create.yaml create mode 100644 paths/pre_translations/index.yaml create mode 100644 paths/pre_translations/show.yaml create mode 100644 schemas/pre_translation.yaml diff --git a/doc/compiled.json b/doc/compiled.json index 4db8fea82..64453a9d2 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -147,6 +147,9 @@ { "name": "Organization Job Templates" }, + { + "name": "Pre Translations" + }, { "name": "Projects" }, @@ -2886,6 +2889,53 @@ "updated_at": "2015-01-28T09:52:53Z" } }, + "pre_translation": { + "type": "object", + "properties": { + "id": { + "type": "string", + "example": "abcd1234cdef1234abcd1234cdef1234" + }, + "status": { + "type": "string", + "enum": [ + "pending", + "running", + "success", + "error" + ], + "description": "Current execution state of the pre-translation job. Jobs start as `pending` while queued, transition to `running` while executing, and settle to `success` or `error`.\n" + }, + "translatable_type": { + "type": "string", + "enum": [ + "locale", + "job", + "translation_key", + "upload" + ], + "description": "Resource type that was pre-translated." + }, + "translatable_id": { + "type": "string", + "description": "ID of the targeted resource (locale ID, job ID, key ID, or upload ID).", + "example": "abcd1234cdef1234abcd1234cdef1234" + }, + "error": { + "type": "string", + "nullable": true, + "description": "Error message. `null` unless the job's status is `error`." + }, + "created_at": { + "type": "string", + "format": "date-time" + }, + "updated_at": { + "type": "string", + "format": "date-time" + } + } + }, "translation_version": { "type": "object", "title": "translation_version", @@ -16224,6 +16274,239 @@ "x-cli-version": "2.5" } }, + "/projects/{project_id}/pre_translations": { + "get": { + "summary": "List pre-translation jobs", + "description": "Returns all pre-translation jobs scoped to a project, ordered by\ncreation date descending.\n", + "operationId": "pre_translations/list", + "tags": [ + "Pre Translations" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/If-Modified-Since" + }, + { + "$ref": "#/components/parameters/If-None-Match" + }, + { + "$ref": "#/components/parameters/project_id" + }, + { + "$ref": "#/components/parameters/page" + }, + { + "$ref": "#/components/parameters/per_page" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/pre_translation" + } + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + }, + "Link": { + "$ref": "#/components/headers/Link" + }, + "Pagination": { + "$ref": "#/components/headers/Pagination" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to list pre-translation jobs in this project, or when the account does not have the `autopilot` plan feature." + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + } + }, + "post": { + "summary": "Create a pre-translation job", + "description": "Triggers a pre-translation job for a resource within a project, addressed\nby `translatable_type` (`locale`, `job`, `translation_key`, or `upload`)\nand `translatable_id` (its ID).\n\nEnqueues machine translation using the project's configured MT engine.\nReturns 202 Accepted immediately; the job itself runs asynchronously.\n", + "operationId": "pre_translation/create", + "tags": [ + "Pre Translations" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/project_id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "pre_translation/create/parameters", + "properties": { + "translatable_type": { + "type": "string", + "enum": [ + "locale", + "job", + "translation_key", + "upload" + ], + "description": "Resource type to pre-translate." + }, + "translatable_id": { + "type": "string", + "description": "ID of the targeted resource: locale ID for `locale`, job ID for `job`, key ID for `translation_key`, upload ID for `upload`.\n" + } + }, + "example": { + "translatable_type": "locale", + "translatable_id": "abcd1234cdef1234abcd1234cdef1234" + } + } + } + } + }, + "responses": { + "202": { + "description": "Accepted", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/pre_translation" + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to create pre-translation jobs in this project, when the project is protected, or when the account does not have the `autopilot` plan feature." + }, + "404": { + "$ref": "#/components/responses/404" + }, + "422": { + "$ref": "#/components/responses/422" + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, + "/projects/{project_id}/pre_translations/{id}": { + "get": { + "summary": "Get a single pre-translation job", + "description": "Returns a single pre-translation job identified by its ID.\n", + "operationId": "pre_translation/show", + "tags": [ + "Pre Translations" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/If-Modified-Since" + }, + { + "$ref": "#/components/parameters/If-None-Match" + }, + { + "$ref": "#/components/parameters/project_id" + }, + { + "$ref": "#/components/parameters/id" + } + ], + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/pre_translation" + } + } + }, + "headers": { + "X-Rate-Limit-Limit": { + "$ref": "#/components/headers/X-Rate-Limit-Limit" + }, + "X-Rate-Limit-Remaining": { + "$ref": "#/components/headers/X-Rate-Limit-Remaining" + }, + "X-Rate-Limit-Reset": { + "$ref": "#/components/headers/X-Rate-Limit-Reset" + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403", + "description": "Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read pre-translation jobs in this project, or when the account does not have the `autopilot` plan feature." + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + } + } + }, "/projects/{project_id}/uploads": { "post": { "summary": "Upload a new file", diff --git a/main.yaml b/main.yaml index c52b9768d..e6448e767 100644 --- a/main.yaml +++ b/main.yaml @@ -197,6 +197,7 @@ tags: - name: Organization Job Template Locales - name: Organization Job Templates + - name: Pre Translations - name: Projects - name: Quality - name: Releases diff --git a/paths.yaml b/paths.yaml index 07c050486..645fb6844 100644 --- a/paths.yaml +++ b/paths.yaml @@ -283,6 +283,14 @@ "/projects/{project_id}/webhooks/{id}/test": post: "$ref": "./paths/webhooks/test.yaml" +"/projects/{project_id}/pre_translations": + get: + "$ref": "./paths/pre_translations/index.yaml" + post: + "$ref": "./paths/pre_translations/create.yaml" +"/projects/{project_id}/pre_translations/{id}": + get: + "$ref": "./paths/pre_translations/show.yaml" "/projects/{project_id}/uploads": post: "$ref": "./paths/uploads/create.yaml" diff --git a/paths/pre_translations/create.yaml b/paths/pre_translations/create.yaml new file mode 100644 index 000000000..e08b895e9 --- /dev/null +++ b/paths/pre_translations/create.yaml @@ -0,0 +1,67 @@ +--- +summary: Create a pre-translation job +description: | + Triggers a pre-translation job for a resource within a project, addressed + by `translatable_type` (`locale`, `job`, `translation_key`, or `upload`) + and `translatable_id` (its ID). + + Enqueues machine translation using the project's configured MT engine. + Returns 202 Accepted immediately; the job itself runs asynchronously. +operationId: pre_translation/create +tags: +- Pre Translations +parameters: +- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" +- "$ref": "../../parameters.yaml#/project_id" +requestBody: + required: true + content: + application/json: + schema: + type: object + title: pre_translation/create/parameters + properties: + translatable_type: + type: string + enum: + - locale + - job + - translation_key + - upload + description: Resource type to pre-translate. + translatable_id: + type: string + description: > + ID of the targeted resource: locale ID for `locale`, job ID + for `job`, key ID for `translation_key`, upload ID for + `upload`. + example: + translatable_type: locale + translatable_id: abcd1234cdef1234abcd1234cdef1234 +responses: + '202': + description: Accepted + content: + application/json: + schema: + "$ref": "../../schemas/pre_translation.yaml#/pre_translation" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + description: Forbidden. Returned when the access token lacks the `write` scope, when the requesting user is not allowed to create pre-translation jobs in this project, when the project is protected, or when the account does not have the `autopilot` plan feature. + '404': + "$ref": "../../responses.yaml#/404" + '422': + "$ref": "../../responses.yaml#/422" + '429': + "$ref": "../../responses.yaml#/429" diff --git a/paths/pre_translations/index.yaml b/paths/pre_translations/index.yaml new file mode 100644 index 000000000..8a4258567 --- /dev/null +++ b/paths/pre_translations/index.yaml @@ -0,0 +1,46 @@ +--- +summary: List pre-translation jobs +description: | + Returns all pre-translation jobs scoped to a project, ordered by + creation date descending. +operationId: pre_translations/list +tags: +- Pre Translations +parameters: +- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" +- "$ref": "../../parameters.yaml#/If-Modified-Since" +- "$ref": "../../parameters.yaml#/If-None-Match" +- "$ref": "../../parameters.yaml#/project_id" +- "$ref": "../../parameters.yaml#/page" +- "$ref": "../../parameters.yaml#/per_page" +responses: + '200': + description: OK + content: + application/json: + schema: + type: array + items: + "$ref": "../../schemas/pre_translation.yaml#/pre_translation" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + Link: + "$ref": "../../headers.yaml#/Link" + Pagination: + "$ref": "../../headers.yaml#/Pagination" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to list pre-translation jobs in this project, or when the account does not have the `autopilot` plan feature. + '404': + "$ref": "../../responses.yaml#/404" + '429': + "$ref": "../../responses.yaml#/429" diff --git a/paths/pre_translations/show.yaml b/paths/pre_translations/show.yaml new file mode 100644 index 000000000..191e76284 --- /dev/null +++ b/paths/pre_translations/show.yaml @@ -0,0 +1,38 @@ +--- +summary: Get a single pre-translation job +description: | + Returns a single pre-translation job identified by its ID. +operationId: pre_translation/show +tags: +- Pre Translations +parameters: +- "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" +- "$ref": "../../parameters.yaml#/If-Modified-Since" +- "$ref": "../../parameters.yaml#/If-None-Match" +- "$ref": "../../parameters.yaml#/project_id" +- "$ref": "../../parameters.yaml#/id" +responses: + '200': + description: OK + content: + application/json: + schema: + "$ref": "../../schemas/pre_translation.yaml#/pre_translation" + headers: + X-Rate-Limit-Limit: + "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" + X-Rate-Limit-Remaining: + "$ref": "../../headers.yaml#/X-Rate-Limit-Remaining" + X-Rate-Limit-Reset: + "$ref": "../../headers.yaml#/X-Rate-Limit-Reset" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + description: Forbidden. Returned when the access token lacks the `read` scope, when the requesting user is not allowed to read pre-translation jobs in this project, or when the account does not have the `autopilot` plan feature. + '404': + "$ref": "../../responses.yaml#/404" + '429': + "$ref": "../../responses.yaml#/429" diff --git a/schemas.yaml b/schemas.yaml index 02c46b8f4..b7c4a2e27 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -94,6 +94,8 @@ schemas: "$ref": schemas/affected_resources.yaml#/affected_resources translation_order: "$ref": schemas/translation_order.yaml#/translation_order + pre_translation: + "$ref": schemas/pre_translation.yaml#/pre_translation translation_version: "$ref": schemas/translation_version.yaml#/translation_version translation_version_with_user: diff --git a/schemas/pre_translation.yaml b/schemas/pre_translation.yaml new file mode 100644 index 000000000..a1f89851c --- /dev/null +++ b/schemas/pre_translation.yaml @@ -0,0 +1,40 @@ +--- +pre_translation: + type: object + properties: + id: + type: string + example: "abcd1234cdef1234abcd1234cdef1234" + status: + type: string + enum: + - pending + - running + - success + - error + description: > + Current execution state of the pre-translation job. Jobs start as + `pending` while queued, transition to `running` while executing, + and settle to `success` or `error`. + translatable_type: + type: string + enum: + - locale + - job + - translation_key + - upload + description: Resource type that was pre-translated. + translatable_id: + type: string + description: ID of the targeted resource (locale ID, job ID, key ID, or upload ID). + example: "abcd1234cdef1234abcd1234cdef1234" + error: + type: string + nullable: true + description: Error message. `null` unless the job's status is `error`. + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time From 3293c1791eac45c4d59c3813ad7596b67b604ae4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6nke=20Behrendt?= Date: Fri, 24 Jul 2026 15:14:59 +0200 Subject: [PATCH 2/2] Shorten create description --- doc/compiled.json | 2 +- paths/pre_translations/create.yaml | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index 64453a9d2..6e13a88a6 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -16353,7 +16353,7 @@ }, "post": { "summary": "Create a pre-translation job", - "description": "Triggers a pre-translation job for a resource within a project, addressed\nby `translatable_type` (`locale`, `job`, `translation_key`, or `upload`)\nand `translatable_id` (its ID).\n\nEnqueues machine translation using the project's configured MT engine.\nReturns 202 Accepted immediately; the job itself runs asynchronously.\n", + "description": "Triggers a pre-translation job for a resource within a project, addressed\nby `translatable_type` (`locale`, `job`, `translation_key`, or `upload`)\nand `translatable_id` (its ID).\n\nEnqueues machine translation using the project's configured MT engine.\n", "operationId": "pre_translation/create", "tags": [ "Pre Translations" diff --git a/paths/pre_translations/create.yaml b/paths/pre_translations/create.yaml index e08b895e9..27ba8d6d8 100644 --- a/paths/pre_translations/create.yaml +++ b/paths/pre_translations/create.yaml @@ -6,7 +6,6 @@ description: | and `translatable_id` (its ID). Enqueues machine translation using the project's configured MT engine. - Returns 202 Accepted immediately; the job itself runs asynchronously. operationId: pre_translation/create tags: - Pre Translations