chore: generate and update OAS for translations (#14281)

* chore: generate and update OAS for translations

* support localization header

* add locale to all store routes

* fixes

* small fix
This commit is contained in:
Shahed Nasser
2025-12-16 15:52:33 +02:00
committed by GitHub
parent 6815b3d7db
commit 53cdbaa069
75 changed files with 2322 additions and 6 deletions
@@ -0,0 +1,152 @@
/**
* @oas [get] /admin/locales
* operationId: GetLocales
* summary: List Locales
* description: Retrieve a list of locales. The locales can be filtered by fields such as `code`. The locales can also be sorted or paginated.
* x-authenticated: true
* parameters:
* - name: q
* in: query
* description: Search query to filter locales by code or other fields.
* required: false
* schema:
* type: string
* title: q
* description: Search query to filter locales by code or other fields.
* - name: code
* in: query
* required: false
* schema:
* oneOf:
* - type: string
* title: code
* description: Filter locales by a code.
* - type: array
* description: Filter locales by multiple codes.
* items:
* type: string
* title: code
* description: A locale code.
* - name: limit
* in: query
* description: Limit the number of items returned in the list.
* required: false
* schema:
* type: number
* title: limit
* description: Limit the number of items returned in the list.
* externalDocs:
* url: "#pagination"
* - name: offset
* in: query
* description: The number of items to skip when retrieving a list.
* required: false
* schema:
* type: number
* title: offset
* description: The number of items to skip when retrieving a list.
* externalDocs:
* url: "#pagination"
* - name: order
* in: query
* description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
* required: false
* schema:
* type: string
* title: order
* description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
* externalDocs:
* url: "#pagination"
* - name: with_deleted
* in: query
* description: The locale's with deleted.
* required: false
* schema:
* type: boolean
* title: with_deleted
* description: The locale's with deleted.
* - name: fields
* in: query
* description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
* fields. Without prefix it will replace the entire default fields.
* required: false
* schema:
* type: string
* title: fields
* description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
* fields. Without prefix it will replace the entire default fields.
* externalDocs:
* url: "#select-fields-and-relations"
* - name: $and
* in: query
* description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
* required: false
* schema:
* type: array
* description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
* items:
* type: object
* title: $and
* - name: $or
* in: query
* description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
* required: false
* schema:
* type: array
* description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
* items:
* type: object
* title: $or
* security:
* - api_token: []
* - cookie_auth: []
* - jwt_token: []
* x-codeSamples:
* - lang: JavaScript
* label: JS SDK
* source: |-
* import Medusa from "@medusajs/js-sdk"
*
* export const sdk = new Medusa({
* baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
* debug: import.meta.env.DEV,
* auth: {
* type: "session",
* },
* })
*
* sdk.admin.locale.list()
* .then(({ locales, count, limit, offset }) => {
* console.log(locales)
* })
* - lang: Shell
* label: cURL
* source: |-
* curl '{backend_url}/admin/locales' \
* -H 'Authorization: Bearer {access_token}'
* tags:
* - Locales
* responses:
* "200":
* description: OK
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/AdminLocaleListResponse"
* "400":
* $ref: "#/components/responses/400_error"
* "401":
* $ref: "#/components/responses/unauthorized"
* "404":
* $ref: "#/components/responses/not_found_error"
* "409":
* $ref: "#/components/responses/invalid_state_error"
* "422":
* $ref: "#/components/responses/invalid_request_error"
* "500":
* $ref: "#/components/responses/500_error"
* x-since: 2.12.3
* x-featureFlag: translation
*
*/
@@ -0,0 +1,80 @@
/**
* @oas [get] /admin/locales/{code}
* operationId: GetLocalesCode
* summary: Get a Locale
* x-sidebar-summary: Get Locale
* description: Retrieve a locale by its code. You can expand the locale's relations or select the fields that should be returned.
* x-authenticated: true
* parameters:
* - name: code
* in: path
* description: The locale's code in [BCP 47 format](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1).
* example: fr-FR
* required: true
* schema:
* type: string
* - name: fields
* in: query
* description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
* fields. Without prefix it will replace the entire default fields.
* required: false
* schema:
* type: string
* title: fields
* description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
* fields. Without prefix it will replace the entire default fields.
* externalDocs:
* url: "#select-fields-and-relations"
* security:
* - api_token: []
* - cookie_auth: []
* - jwt_token: []
* x-codeSamples:
* - lang: JavaScript
* label: JS SDK
* source: |-
* import Medusa from "@medusajs/js-sdk"
*
* export const sdk = new Medusa({
* baseUrl: import.meta.env.VITE_BACKEND_URL || "/",
* debug: import.meta.env.DEV,
* auth: {
* type: "session",
* },
* })
*
* sdk.admin.locale.retrieve("en-US")
* .then(({ locale }) => {
* console.log(locale)
* })
* - lang: Shell
* label: cURL
* source: |-
* curl '{backend_url}/admin/locales/fr-FR' \
* -H 'Authorization: Bearer {access_token}'
* tags:
* - Locales
* responses:
* "200":
* description: OK
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/AdminLocaleResponse"
* "400":
* $ref: "#/components/responses/400_error"
* "401":
* $ref: "#/components/responses/unauthorized"
* "404":
* $ref: "#/components/responses/not_found_error"
* "409":
* $ref: "#/components/responses/invalid_state_error"
* "422":
* $ref: "#/components/responses/invalid_request_error"
* "500":
* $ref: "#/components/responses/500_error"
* x-since: 2.12.3
* x-featureFlag: translation
*
*/
@@ -0,0 +1,195 @@
/**
* @oas [get] /admin/translations
* operationId: GetTranslations
* summary: List Translations
* description: Retrieve a list of translations. The translations can be filtered by fields such as `reference_id` (For example, the ID of a product). The translations can also be sorted or paginated.
* x-authenticated: true
* parameters:
* - name: q
* in: query
* description: Search query to filter translations by their fields.
* required: false
* schema:
* type: string
* title: q
* description: Search query to filter translations by their fields.
* - name: reference_id
* in: query
* required: false
* schema:
* oneOf:
* - type: string
* title: reference_id
* description: Filter translations by a reference ID. For example, the ID of a product.
* example: prod_123
* - type: array
* description: Filter translations by multiple reference IDs. For example, the IDs of products.
* items:
* type: string
* title: reference_id
* description: The reference ID's details. For example, the ID of a product.
* example: prod_123
* - name: reference
* in: query
* description: Filter translations by the resource they belong to. For example, `product` or `product_variant`.
* required: false
* schema:
* type: string
* title: reference
* description: Filter translations by the resource they belong to. For example, `product` or `product_variant`.
* - name: locale_code
* in: query
* required: false
* schema:
* oneOf:
* - type: string
* title: locale_code
* description: Filter translations by a locale code in BCP 47 format.
* example: fr-FR
* - type: array
* description: Filter translations by multiple locale codes in BCP 47 format.
* items:
* type: string
* title: locale_code
* description: A locale code in BCP 47 format.
* example: fr-FR
* - name: limit
* in: query
* description: Limit the number of items returned in the list.
* required: false
* schema:
* type: number
* title: limit
* description: Limit the number of items returned in the list.
* externalDocs:
* url: "#pagination"
* - name: offset
* in: query
* description: The number of items to skip when retrieving a list.
* required: false
* schema:
* type: number
* title: offset
* description: The number of items to skip when retrieving a list.
* externalDocs:
* url: "#pagination"
* - name: order
* in: query
* description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
* required: false
* schema:
* type: string
* title: order
* description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
* externalDocs:
* url: "#pagination"
* - name: with_deleted
* in: query
* description: The translation's with deleted.
* required: false
* schema:
* type: boolean
* title: with_deleted
* description: The translation's with deleted.
* - name: fields
* in: query
* description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
* fields. Without prefix it will replace the entire default fields.
* required: false
* schema:
* type: string
* title: fields
* description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default
* fields. Without prefix it will replace the entire default fields.
* externalDocs:
* url: "#select-fields-and-relations"
* - name: $and
* in: query
* description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
* required: false
* schema:
* type: array
* description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
* items:
* type: object
* title: $and
* - name: $or
* in: query
* description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
* required: false
* schema:
* type: array
* description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
* items:
* type: object
* title: $or
* security:
* - api_token: []
* - cookie_auth: []
* - jwt_token: []
* x-codeSamples:
* - lang: Shell
* label: cURL
* source: |-
* curl '{backend_url}/admin/translations' \
* -H 'Authorization: Bearer {access_token}'
* tags:
* - Translations
* responses:
* "200":
* description: OK
* content:
* application/json:
* schema:
* allOf:
* - type: object
* description: The list of translations with pagination.
* required:
* - limit
* - offset
* - count
* properties:
* limit:
* type: number
* title: limit
* description: The maximum number of translations returned.
* offset:
* type: number
* title: offset
* description: The number of translations skipped before retrieving the returned translations.
* count:
* type: number
* title: count
* description: The total number of translations matching the query.
* estimate_count:
* type: number
* title: estimate_count
* description: The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
* x-featureFlag: index_engine
* - type: object
* description: SUMMARY
* required:
* - translations
* properties:
* translations:
* type: array
* description: The list of translations.
* items:
* $ref: "#/components/schemas/AdminTranslation"
* "400":
* $ref: "#/components/responses/400_error"
* "401":
* $ref: "#/components/responses/unauthorized"
* "404":
* $ref: "#/components/responses/not_found_error"
* "409":
* $ref: "#/components/responses/invalid_state_error"
* "422":
* $ref: "#/components/responses/invalid_request_error"
* "500":
* $ref: "#/components/responses/500_error"
* x-since: 2.12.3
* x-featureFlag: translation
*
*/
@@ -0,0 +1,44 @@
/**
* @oas [get] /admin/translations/settings
* operationId: GetTranslationsSettings
* summary: List Translation Settings
* x-sidebar-summary: List Settings
* description: Retrieve the list of translatable fields for all entities, such as products and collections.
* x-authenticated: true
* parameters: []
* security:
* - api_token: []
* - cookie_auth: []
* - jwt_token: []
* x-codeSamples:
* - lang: Shell
* label: cURL
* source: |-
* curl '{backend_url}/admin/translations/settings' \
* -H 'Authorization: Bearer {access_token}'
* tags:
* - Translations
* responses:
* "200":
* description: OK
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/AdminTranslationSettingsResponse"
* "400":
* $ref: "#/components/responses/400_error"
* "401":
* $ref: "#/components/responses/unauthorized"
* "404":
* $ref: "#/components/responses/not_found_error"
* "409":
* $ref: "#/components/responses/invalid_state_error"
* "422":
* $ref: "#/components/responses/invalid_request_error"
* "500":
* $ref: "#/components/responses/500_error"
* x-since: 2.12.3
* x-featureFlag: translation
*
*/
@@ -0,0 +1,69 @@
/**
* @oas [get] /admin/translations/statistics
* operationId: GetTranslationsStatistics
* summary: Retrieve Translation Statistics
* x-sidebar-summary: Get Statistics
* description: Get statistics on translations for specified locales and entity types. This includes overall
* translation progress for each entity type, and statistics for each locale within those entity types.
* x-authenticated: true
* parameters:
* - name: locales
* in: query
* description: The locale codes to retrieve translation statistics for. Locale codes are in [BCP 47](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) format.
* required: true
* schema:
* type: array
* description: The locale codes to retrieve translation statistics for.
* items:
* type: string
* title: locales
* description: A locale code in [BCP 47](https://gist.github.com/typpo/b2b828a35e683b9bf8db91b5404f1bd1) format.
* example: "fr-FR"
* - name: entity_types
* in: query
* description: The table names of entities to retrieve translation statistics for.
* required: true
* schema:
* type: array
* description: The table names of entities to retrieve translation statistics for.
* items:
* type: string
* title: entity_types
* description: The table name of an entity.
* example: products
* security:
* - api_token: []
* - cookie_auth: []
* - jwt_token: []
* x-codeSamples:
* - lang: Shell
* label: cURL
* source: |-
* curl '{backend_url}/admin/translations/statistics' \
* -H 'Authorization: Bearer {access_token}'
* tags:
* - Translations
* responses:
* "200":
* description: OK
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/AdminTranslationStatisticsResponse"
* "400":
* $ref: "#/components/responses/400_error"
* "401":
* $ref: "#/components/responses/unauthorized"
* "404":
* $ref: "#/components/responses/not_found_error"
* "409":
* $ref: "#/components/responses/invalid_state_error"
* "422":
* $ref: "#/components/responses/invalid_request_error"
* "500":
* $ref: "#/components/responses/500_error"
* x-since: 2.12.3
* x-featureFlag: translation
*
*/
@@ -0,0 +1,170 @@
/**
* @oas [post] /admin/translations/batch
* operationId: PostTranslationsBatch
* summary: Manage Translations
* description: Manage translations in bulk by creating, updating, or deleting multiple translations in a single request. You can manage translations for various resources such as products, product
* variants, categories, and more.
* x-authenticated: true
* security:
* - api_token: []
* - cookie_auth: []
* - jwt_token: []
* requestBody:
* content:
* application/json:
* schema:
* type: object
* description: The translations to be created, updated, or deleted in bulk.
* properties:
* create:
* type: array
* description: The translations to create.
* items:
* type: object
* description: The translation's details.
* required:
* - reference
* - reference_id
* - locale_code
* - translations
* properties:
* reference:
* type: string
* title: reference
* description: The resource that the translation belongs to.
* example: product
* reference_id:
* type: string
* title: reference_id
* description: The ID of the resource that the translation belongs to. For example, the ID of a product.
* example: prod_123
* locale_code:
* type: string
* title: locale_code
* description: The translation's locale code in BCP 47 format.
* example: fr-FR
* translations:
* type: object
* description: The translation key-value pairs. Each key is a field in the resource, and the value is the translated text.
* example:
* title: Chaussures
* description: Des chaussures élégantes.
* update:
* type: array
* description: The translations to update.
* items:
* type: object
* description: The data for updating a translation.
* required:
* - id
* properties:
* id:
* type: string
* title: id
* description: The ID of the translation to update.
* reference:
* type: string
* title: reference
* description: The resource that the translation belongs to.
* example: product
* reference_id:
* type: string
* title: reference_id
* description: The ID of the resource that the translation belongs to. For example, the ID of a product.
* example: prod_123
* locale_code:
* type: string
* title: locale_code
* description: The translation's locale code in BCP 47 format.
* example: fr-FR
* translations:
* type: object
* description: The translation key-value pairs. Each key is a field in the resource, and the value is the translated text.
* example:
* title: Chaussures Modifiées
* description: Des chaussures élégantes et modifiées.
* delete:
* type: array
* description: The translations to delete.
* items:
* type: string
* title: delete
* description: The ID of a translation to delete.
* x-codeSamples:
* - lang: Shell
* label: cURL
* source: |-
* curl -X POST '{backend_url}/admin/translations/batch' \
* -H 'Authorization: Bearer {access_token}' \
* -H 'Content-Type: application/json' \
* -d '{
* "create": [
* {
* "reference": "product",
* "reference_id": "prod_123",
* "locale_code": "fr-FR",
* "translations": {
* "title": "Chaussures",
* "description": "Des chaussures élégantes."
* }
* }
* ]
* }'
* tags:
* - Translations
* responses:
* "200":
* description: OK
* content:
* application/json:
* schema:
* $ref: "#/components/schemas/AdminTranslationsBatchResponse"
* "400":
* $ref: "#/components/responses/400_error"
* "401":
* $ref: "#/components/responses/unauthorized"
* "404":
* $ref: "#/components/responses/not_found_error"
* "409":
* $ref: "#/components/responses/invalid_state_error"
* "422":
* $ref: "#/components/responses/invalid_request_error"
* "500":
* $ref: "#/components/responses/500_error"
* x-workflow: batchTranslationsWorkflow
* x-events:
* - name: translation.created
* payload: |-
* ```ts
* {
* id, // The ID of the translation
* }
* ```
* description: Emitted when translations are created.
* deprecated: false
* since: 2.12.3
* - name: translation.updated
* payload: |-
* ```ts
* {
* id, // The ID of the translation
* }
* ```
* description: Emitted when translations are updated.
* deprecated: false
* since: 2.12.3
* - name: translation.deleted
* payload: |-
* ```ts
* {
* id, // The ID of the translation
* }
* ```
* description: Emitted when translations are deleted.
* deprecated: false
* since: 2.12.3
* x-since: 2.12.3
* x-featureFlag: translation
*
*/