diff --git a/doc/compiled.json b/doc/compiled.json index e2f2d221..b75a6703 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -130,6 +130,9 @@ { "name": "Locale Downloads" }, + { + "name": "Machine Translation" + }, { "name": "Members", "description": "With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.\n" @@ -5251,6 +5254,54 @@ }, "details": null } + }, + "machine_translation_settings": { + "type": "object", + "properties": { + "default_service": { + "type": "string", + "nullable": true, + "description": "The default machine translation engine configured for the account. Returns \"microsoft_translate\" when no service has been explicitly configured. Supported values: language_ai_translate, aita_translate, microsoft_translate, google_translate, amazon_translate, intento_translate, gpt_translate.\n", + "example": "google_translate" + }, + "machine_translation_units_used": { + "type": "integer", + "description": "Number of machine translation characters consumed in the current billing period.", + "example": 12500 + }, + "machine_translation_units_total": { + "type": "integer", + "description": "Total machine translation character quota granted for the current billing period.", + "example": 1000000 + }, + "locale_provider_mappings": { + "type": "array", + "description": "Per-locale-pair provider overrides. When a matching mapping exists for a source/target locale pair, that provider takes precedence over the account default.\n", + "items": { + "$ref": "#/components/schemas/machine_translation_locale_provider_mapping" + } + } + } + }, + "machine_translation_locale_provider_mapping": { + "type": "object", + "properties": { + "source_locale_code": { + "type": "string", + "description": "The locale code of the source language for this mapping.", + "example": "en" + }, + "target_locale_code": { + "type": "string", + "description": "The locale code of the target language for this mapping.", + "example": "de" + }, + "service": { + "type": "string", + "description": "The translation service applied when translating from source to target locale.", + "example": "google_translate" + } + } } }, "parameters": { @@ -33034,6 +33085,360 @@ } ] } + }, + "/accounts/{account_id}/machine_translation_settings": { + "get": { + "operationId": "machine_translation_settings/show", + "summary": "Get machine translation settings", + "description": "Returns the machine translation configuration for the account, including the\ndefault translation service, current machine translation unit usage, and any\nlocale-pair-specific provider mappings.\n", + "tags": [ + "Machine Translation" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + } + ], + "responses": { + "200": { + "description": "OK", + "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" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/machine_translation_settings" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "Basic": [] + }, + { + "Token": [] + }, + { + "OAuthImplicit": [ + "read" + ] + }, + { + "OAuthExplicit": [ + "read" + ] + } + ] + }, + "patch": { + "operationId": "machine_translation_settings/update", + "summary": "Update machine translation settings", + "description": "Sets the default machine translation service for the account. Requires write\naccess to the account's machine translation settings. Passing an empty or\nabsent value for `default_service` resets the account to its plan default\n(Microsoft Translate).\n", + "tags": [ + "Machine Translation" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "machine_translation_settings/update/parameters", + "properties": { + "default_service": { + "type": "string", + "nullable": true, + "description": "The machine translation engine to use as the account default. Supported values: language_ai_translate, aita_translate, microsoft_translate, google_translate, amazon_translate, intento_translate, gpt_translate. Pass null or an empty string to reset to the plan default.\n", + "example": "google_translate" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "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" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/machine_translation_settings" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "422": { + "$ref": "#/components/responses/422" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "Basic": [] + }, + { + "Token": [] + }, + { + "OAuthImplicit": [ + "write" + ] + }, + { + "OAuthExplicit": [ + "write" + ] + } + ] + } + }, + "/accounts/{account_id}/machine_translation_locale_provider_mappings": { + "post": { + "operationId": "machine_translation_locale_provider_mappings/create", + "summary": "Create a locale provider mapping", + "description": "Creates a locale-pair-specific machine translation provider override for the\naccount. When a mapping exists for a given source/target locale pair, that\nprovider is used instead of the account default. Only one mapping may exist\nper source/target locale pair; attempting to create a duplicate returns a\nvalidation error. The source and target locale codes must differ.\n", + "tags": [ + "Machine Translation" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "machine_translation_locale_provider_mappings/create/parameters", + "required": [ + "source_locale_code", + "target_locale_code", + "service" + ], + "properties": { + "source_locale_code": { + "type": "string", + "description": "The locale code of the source language (e.g. \"en\").", + "example": "en" + }, + "target_locale_code": { + "type": "string", + "description": "The locale code of the target language (e.g. \"de\"). Must differ from source_locale_code.\n", + "example": "de" + }, + "service": { + "type": "string", + "description": "The machine translation service to use for this locale pair. Must be a service enabled for the account.\n", + "example": "google_translate" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Created", + "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" + } + }, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/machine_translation_locale_provider_mapping" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "422": { + "$ref": "#/components/responses/422" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "Basic": [] + }, + { + "Token": [] + }, + { + "OAuthImplicit": [ + "write" + ] + }, + { + "OAuthExplicit": [ + "write" + ] + } + ] + }, + "delete": { + "operationId": "machine_translation_locale_provider_mappings/destroy", + "summary": "Delete a locale provider mapping", + "description": "Removes the machine translation provider override for the specified source\nand target locale pair. The mapping is identified by locale codes supplied\nas query parameters rather than a path ID.\n", + "tags": [ + "Machine Translation" + ], + "parameters": [ + { + "$ref": "#/components/parameters/X-PhraseApp-OTP" + }, + { + "$ref": "#/components/parameters/account_id" + }, + { + "name": "source_locale_code", + "in": "query", + "required": true, + "schema": { + "type": "string" + }, + "description": "The locale code of the source language of the mapping to delete.", + "example": "en" + }, + { + "name": "target_locale_code", + "in": "query", + "required": true, + "schema": { + "type": "string" + }, + "description": "The locale code of the target language of the mapping to delete.", + "example": "de" + } + ], + "responses": { + "204": { + "description": "The resource was deleted successfully.", + "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" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "429": { + "$ref": "#/components/responses/429" + } + }, + "security": [ + { + "Basic": [] + }, + { + "Token": [] + }, + { + "OAuthImplicit": [ + "write" + ] + }, + { + "OAuthExplicit": [ + "write" + ] + } + ] + } } } } diff --git a/main.yaml b/main.yaml index 7c272847..33c0e94b 100644 --- a/main.yaml +++ b/main.yaml @@ -141,6 +141,7 @@ tags: - name: Linked Keys - name: Locales - name: Locale Downloads + - name: Machine Translation - name: Members description: | With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them. diff --git a/paths.yaml b/paths.yaml index 8cd0e974..b998da7b 100644 --- a/paths.yaml +++ b/paths.yaml @@ -762,3 +762,13 @@ "/accounts/{account_id}/automation_events": get: "$ref": "./paths/automation_events/index.yaml" +"/accounts/{account_id}/machine_translation_settings": + get: + "$ref": "./paths/machine_translation_settings/show.yaml" + patch: + "$ref": "./paths/machine_translation_settings/update.yaml" +"/accounts/{account_id}/machine_translation_locale_provider_mappings": + post: + "$ref": "./paths/machine_translation_locale_provider_mappings/create.yaml" + delete: + "$ref": "./paths/machine_translation_locale_provider_mappings/destroy-collection.yaml" diff --git a/paths/machine_translation_locale_provider_mappings/create.yaml b/paths/machine_translation_locale_provider_mappings/create.yaml new file mode 100644 index 00000000..b0794dc1 --- /dev/null +++ b/paths/machine_translation_locale_provider_mappings/create.yaml @@ -0,0 +1,73 @@ +--- +operationId: machine_translation_locale_provider_mappings/create +summary: Create a locale provider mapping +description: | + Creates a locale-pair-specific machine translation provider override for the + account. When a mapping exists for a given source/target locale pair, that + provider is used instead of the account default. Only one mapping may exist + per source/target locale pair; attempting to create a duplicate returns a + validation error. The source and target locale codes must differ. +tags: + - Machine Translation +parameters: + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/account_id" +requestBody: + required: true + content: + application/json: + schema: + type: object + title: machine_translation_locale_provider_mappings/create/parameters + required: + - source_locale_code + - target_locale_code + - service + properties: + source_locale_code: + type: string + description: The locale code of the source language (e.g. "en"). + example: en + target_locale_code: + type: string + description: > + The locale code of the target language (e.g. "de"). + Must differ from source_locale_code. + example: de + service: + type: string + description: > + The machine translation service to use for this locale pair. + Must be a service enabled for the account. + example: google_translate +responses: + '201': + description: Created + 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" + content: + application/json: + schema: + "$ref": "../../schemas/machine_translation_locale_provider_mapping.yaml#/machine_translation_locale_provider_mapping" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + '422': + "$ref": "../../responses.yaml#/422" + '429': + "$ref": "../../responses.yaml#/429" +security: + - Basic: [] + - Token: [] + - OAuthImplicit: + - write + - OAuthExplicit: + - write diff --git a/paths/machine_translation_locale_provider_mappings/destroy-collection.yaml b/paths/machine_translation_locale_provider_mappings/destroy-collection.yaml new file mode 100644 index 00000000..872ed28f --- /dev/null +++ b/paths/machine_translation_locale_provider_mappings/destroy-collection.yaml @@ -0,0 +1,53 @@ +--- +operationId: machine_translation_locale_provider_mappings/destroy +summary: Delete a locale provider mapping +description: | + Removes the machine translation provider override for the specified source + and target locale pair. The mapping is identified by locale codes supplied + as query parameters rather than a path ID. +tags: + - Machine Translation +parameters: + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/account_id" + - name: source_locale_code + in: query + required: true + schema: + type: string + description: The locale code of the source language of the mapping to delete. + example: en + - name: target_locale_code + in: query + required: true + schema: + type: string + description: The locale code of the target language of the mapping to delete. + example: de +responses: + '204': + description: The resource was deleted successfully. + 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" + '404': + "$ref": "../../responses.yaml#/404" + '429': + "$ref": "../../responses.yaml#/429" +security: + - Basic: [] + - Token: [] + - OAuthImplicit: + - write + - OAuthExplicit: + - write diff --git a/paths/machine_translation_settings/show.yaml b/paths/machine_translation_settings/show.yaml new file mode 100644 index 00000000..fcf3753f --- /dev/null +++ b/paths/machine_translation_settings/show.yaml @@ -0,0 +1,41 @@ +--- +operationId: machine_translation_settings/show +summary: Get machine translation settings +description: | + Returns the machine translation configuration for the account, including the + default translation service, current machine translation unit usage, and any + locale-pair-specific provider mappings. +tags: + - Machine Translation +parameters: + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/account_id" +responses: + '200': + description: OK + 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" + content: + application/json: + schema: + "$ref": "../../schemas/machine_translation_settings.yaml#/machine_translation_settings" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + '429': + "$ref": "../../responses.yaml#/429" +security: + - Basic: [] + - Token: [] + - OAuthImplicit: + - read + - OAuthExplicit: + - read diff --git a/paths/machine_translation_settings/update.yaml b/paths/machine_translation_settings/update.yaml new file mode 100644 index 00000000..5db71045 --- /dev/null +++ b/paths/machine_translation_settings/update.yaml @@ -0,0 +1,62 @@ +--- +operationId: machine_translation_settings/update +summary: Update machine translation settings +description: | + Sets the default machine translation service for the account. Requires write + access to the account's machine translation settings. Passing an empty or + absent value for `default_service` resets the account to its plan default + (Microsoft Translate). +tags: + - Machine Translation +parameters: + - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" + - "$ref": "../../parameters.yaml#/account_id" +requestBody: + required: true + content: + application/json: + schema: + type: object + title: machine_translation_settings/update/parameters + properties: + default_service: + type: string + nullable: true + description: > + The machine translation engine to use as the account default. + Supported values: language_ai_translate, aita_translate, + microsoft_translate, google_translate, amazon_translate, + intento_translate, gpt_translate. Pass null or an empty string + to reset to the plan default. + example: google_translate +responses: + '200': + description: OK + 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" + content: + application/json: + schema: + "$ref": "../../schemas/machine_translation_settings.yaml#/machine_translation_settings" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + '422': + "$ref": "../../responses.yaml#/422" + '429': + "$ref": "../../responses.yaml#/429" +security: + - Basic: [] + - Token: [] + - OAuthImplicit: + - write + - OAuthExplicit: + - write diff --git a/schemas.yaml b/schemas.yaml index a1584bf0..9fefffe9 100644 --- a/schemas.yaml +++ b/schemas.yaml @@ -178,3 +178,7 @@ schemas: "$ref": schemas/automation.yaml#/automation automation_event: "$ref": schemas/automation_event.yaml#/automation_event + machine_translation_settings: + "$ref": schemas/machine_translation_settings.yaml#/machine_translation_settings + machine_translation_locale_provider_mapping: + "$ref": schemas/machine_translation_locale_provider_mapping.yaml#/machine_translation_locale_provider_mapping diff --git a/schemas/machine_translation_locale_provider_mapping.yaml b/schemas/machine_translation_locale_provider_mapping.yaml new file mode 100644 index 00000000..387ffd51 --- /dev/null +++ b/schemas/machine_translation_locale_provider_mapping.yaml @@ -0,0 +1,15 @@ +machine_translation_locale_provider_mapping: + type: object + properties: + source_locale_code: + type: string + description: The locale code of the source language for this mapping. + example: en + target_locale_code: + type: string + description: The locale code of the target language for this mapping. + example: de + service: + type: string + description: The translation service applied when translating from source to target locale. + example: google_translate diff --git a/schemas/machine_translation_settings.yaml b/schemas/machine_translation_settings.yaml new file mode 100644 index 00000000..49feefa7 --- /dev/null +++ b/schemas/machine_translation_settings.yaml @@ -0,0 +1,27 @@ +machine_translation_settings: + type: object + properties: + default_service: + type: string + nullable: true + description: > + The default machine translation engine configured for the account. + Returns "microsoft_translate" when no service has been explicitly configured. + Supported values: language_ai_translate, aita_translate, microsoft_translate, + google_translate, amazon_translate, intento_translate, gpt_translate. + example: google_translate + machine_translation_units_used: + type: integer + description: Number of machine translation characters consumed in the current billing period. + example: 12500 + machine_translation_units_total: + type: integer + description: Total machine translation character quota granted for the current billing period. + example: 1000000 + locale_provider_mappings: + type: array + description: > + Per-locale-pair provider overrides. When a matching mapping exists for a + source/target locale pair, that provider takes precedence over the account default. + items: + "$ref": "./machine_translation_locale_provider_mapping.yaml#/machine_translation_locale_provider_mapping"