@shipeasy/openapi 1.5.0 → 2.1.0

package/spec/paths/i18n.yaml

@@ -0,0 +1,544 @@
+/api/admin/i18n/profiles:
+  get:
+    operationId: listI18nProfiles
+    summary: List i18n profiles
+    description: |-
+      Returns every locale profile in the project (e.g. `en:prod`, `fr:prod`).
+
+      **Use case:** Discover which locale profiles exist before pushing keys or publishing a chunk.
+    tags:
+      - Profiles
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    responses:
+      "200":
+        description: List i18n profiles
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/ListI18nProfilesResponse
+            example:
+              - id: i18n_01j7w8a1b2c3
+                name: en:prod
+                locales:
+                  - en
+                default_locale: en
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createI18nProfile
+    summary: Create an i18n profile
+    description: |-
+      Create a locale profile. `name` is the stable handle (e.g. `fr:prod`).
+
+      **Use case:** Stand up a new locale before seeding its keys.
+    tags:
+      - Profiles
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/CreateI18nProfileRequest
+          example:
+            name: fr:prod
+            locales:
+              - fr
+            default_locale: fr
+    responses:
+      "201":
+        description: Create an i18n profile
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/CreateI18nProfileResponse
+            example:
+              id: i18n_01j7w8a1b2c4
+              name: fr:prod
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - ALREADY_EXISTS
+      - VALIDATION
+    x-cli:
+      name: create
+/api/admin/i18n/keys:
+  get:
+    operationId: listI18nKeys
+    summary: List i18n keys
+    description: |-
+      List keys for a profile, optionally filtered to a name `prefix`.
+
+      **Use case:** Read the current keys (and values) for a profile — e.g. to diff before a push.
+    tags:
+      - Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: profile_id
+        in: query
+        required: false
+        description: Profile id to list keys for.
+        schema:
+          type: string
+      - name: prefix
+        in: query
+        required: false
+        description: Only keys whose name starts with this.
+        schema:
+          type: string
+      - name: q
+        in: query
+        required: false
+        description: Free-text search — matches keys whose name OR value contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.
+        schema:
+          type: string
+      - name: limit
+        in: query
+        required: false
+        description: Max keys to return (1–500).
+        schema:
+          type: integer
+          minimum: 1
+          maximum: 500
+    responses:
+      "200":
+        description: List i18n keys
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/ListI18nKeysResponse
+            example:
+              keys:
+                - id: key_01j7
+                  key: checkout.cta
+                  value: Buy now
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: pushI18nKeys
+    summary: Push new i18n keys (insert-only)
+    description: |-
+      Add NEW keys to a profile. Insert-only — existing keys are left untouched (overwrite one with `updateI18nKey`).
+
+      **Use case:** Seed newly-extracted keys without clobbering translations already in the profile.
+    tags:
+      - Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/PushI18nKeysRequest
+          example:
+            profile_id: i18n_01j7w8a1b2c3
+            keys:
+              - key: checkout.cta
+                value: Buy now
+    responses:
+      "201":
+        description: Push new i18n keys (insert-only)
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/PushI18nKeysResponse
+            example:
+              added:
+                - checkout.cta
+              skipped: []
+              pushed_count: 1
+              skipped_count: 0
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - ALREADY_EXISTS
+      - VALIDATION
+    x-cli:
+      name: push
+/api/admin/i18n/keys/{id}:
+  put:
+    operationId: updateI18nKey
+    summary: Update one i18n key
+    description: |-
+      Overwrite a single existing key's value — the only overwrite path.
+
+      The change goes live on its own: the profile's KV snapshot is rebuilt and the CDN purged as part of this call, so no separate profile publish is needed.
+
+      **Use case:** Correct or re-translate a single string in place.
+    tags:
+      - Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: The key's id.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/UpdateI18nKeyRequest
+          example:
+            value: Buy it now
+    responses:
+      "200":
+        description: Update one i18n key
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/UpdateI18nKeyResponse
+            example:
+              id: key_01j7
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+/api/admin/i18n/drafts:
+  get:
+    operationId: listI18nDrafts
+    summary: List translation drafts
+    description: |-
+      List staged translation drafts awaiting review/publish.
+
+      **Use case:** Review machine-translation drafts before publishing them to a locale.
+    tags:
+      - Drafts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    responses:
+      "200":
+        description: List translation drafts
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/ListI18nDraftsResponse
+            example:
+              - id: draft_01j7
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createI18nDraft
+    summary: Create a translation draft
+    description: |-
+      Stage a new translation draft against a target profile, optionally seeding its keys from a source profile.
+
+      **Use case:** Open a machine-translation draft for review before publishing it to a locale.
+    tags:
+      - Drafts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/CreateI18nDraftRequest
+          example:
+            name: fr:prod
+            profile_id: 3f1a6c2e-1b2c-4d5e-8f90-0a1b2c3d4e5f
+    responses:
+      "200":
+        description: Create a translation draft
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/CreateI18nDraftResponse
+            example:
+              id: draft_01j7
+              name: fr:prod
+              profileId: 3f1a6c2e-1b2c-4d5e-8f90-0a1b2c3d4e5f
+              status: open
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: create
+/api/admin/i18n/drafts/{draftId}:
+  patch:
+    operationId: updateI18nDraft
+    summary: Update a translation draft
+    description: |-
+      Transition a draft's lifecycle state (`open` / `merged` / `abandoned`).
+
+      **Use case:** Mark a reviewed draft as merged, or abandon one that should not ship.
+    tags:
+      - Drafts
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: draftId
+        in: path
+        required: true
+        description: The draft id to update.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/UpdateI18nDraftRequest
+          example:
+            status: merged
+    responses:
+      "200":
+        description: Update a translation draft
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/UpdateI18nDraftResponse
+            example:
+              id: draft_01j7
+              status: merged
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - draftId
+/api/admin/i18n/profiles/{profileId}/publish:
+  post:
+    operationId: publishI18nProfile
+    summary: Publish a profile live
+    description: |-
+      Publish a profile to the CDN — rebuild its KV snapshot + purge the edge. Publishing is PROFILE-WIDE: the whole profile is snapshotted into one KV blob, so the optional `chunk` in the body is an audit label only (it does not scope what ships).
+
+      **Use case:** Ship the latest translations live after pushing/updating keys.
+    tags:
+      - Profiles
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: profileId
+        in: path
+        required: true
+        description: The profile id to publish.
+        schema:
+          type: string
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/PublishI18nProfileRequest
+          example:
+            chunk: default
+    responses:
+      "201":
+        description: Publish a profile chunk
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/PublishI18nProfileResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: publish
+      positional:
+        - profileId
+/api/admin/i18n/set:
+  post:
+    operationId: setI18nLabel
+    summary: Set a key's value and publish it live
+    description: |-
+      Upsert a single key's value into a profile and immediately publish the whole profile (KV rebuild + CDN purge) so the new value is live in one call. The key is inserted when new and overwritten when it already exists. `profile` is a profile name — omit it to target the project's default-marked profile, or pass a name to target another locale.
+
+      **Use case:** Correct or replace one live string and ship it without a separate `push` + `publish`.
+    tags:
+      - Keys
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/i18n.yaml#/SetI18nLabelRequest
+          example:
+            key: home.cta
+            value: Get started
+    responses:
+      "200":
+        description: Set a key's value and publish it live
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/i18n.yaml#/SetI18nLabelResponse
+            example:
+              ok: true
+              profile: en:prod
+              key: home.cta
+              value: Get started
+              version: "7"
+              key_count: 42
+              changed: true
+              purged: purged
+              kv_verified: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - BAD_REQUEST
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: set
+      positional:
+        - key
+        - value