feat(API): add machine translation settings and locale provider mapping endpoints #STRINGS-2977

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.

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"

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

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

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

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

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

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

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"