Skip to content

feat(API): add pre_translations resource to API #1224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Sönke Behrendt (theSoenke) merged 2 commits into from
Jul 29, 2026
Merged

feat(API): add pre_translations resource to API #1224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e6617ec
add pre_translations resource to API
theSoenke Jul 24, 2026
3293c17
Shorten create description
theSoenke Jul 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
283 changes: 283 additions & 0 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,6 +147,9 @@
{
"name": "Organization Job Templates"
},
{
"name": "Pre Translations"
},
{
"name": "Projects"
},
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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.\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",
Expand Down
1 change: 1 addition & 0 deletions main.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -197,6 +197,7 @@ tags:
</div>
- name: Organization Job Template Locales
- name: Organization Job Templates
- name: Pre Translations
- name: Projects
- name: Quality
- name: Releases
Expand Down
8 changes: 8 additions & 0 deletions paths.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
66 changes: 66 additions & 0 deletions paths/pre_translations/create.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
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.
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"
Loading
Loading