diff --git a/doc/compiled.json b/doc/compiled.json index 50246a1c..5365a97b 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5614,7 +5614,7 @@ "/icu/skeleton": { "post": { "summary": "Build ICU skeletons", - "description": "Returns ICU skeletons for multiple locale codes based on a source content.", + "description": "Generates ICU (International Components for Unicode) message format skeletons for a given source string across one or more locales. An ICU skeleton strips the literal text from a pluralized or select message while preserving its structural rules — argument names, plural categories, select cases, and ordinal forms — adjusted to the pluralization rules of each requested locale.\n\nUse this endpoint to normalize translation templates before importing them into locale files, or to validate that a source string carries the plural forms required by a target language.\n\nEither `content` or `id` must be provided — supplying both or neither returns 400. When `id` is used and the referenced translation does not exist, the endpoint returns 404. When the source string is not valid ICU message format syntax, the endpoint returns 422 with an `error` field describing the parse failure.\n", "operationId": "icu/skeleton", "tags": [ "ICU" @@ -5624,53 +5624,7 @@ "$ref": "#/components/parameters/X-PhraseApp-OTP" } ], - "responses": { - "200": { - "description": "OK", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/icu" - } - } - }, - "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" - } - } - }, - "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." - }, - "404": { - "$ref": "#/components/responses/404" - }, - "429": { - "$ref": "#/components/responses/429" - } - }, "x-code-samples": [ - { - "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/icu/skeleton\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -d '{\"content\":\"{number, plural, one {One} other {%{n}}}\",\"locale_codes\":[\"en\"],\"zero_form_enabled\": true}' \\\n -H 'Content-Type: application/json'" - }, { "lang": "CLI v2", "source": "phrase icu skeleton \\\n--data '{\"content\":\"{number, plural, one {One} other {%{n}}}\",\"locale_codes\":[\"en\"],\"zero_form_enabled\": true}' \\\n--access_token " @@ -5685,44 +5639,120 @@ "title": "icu/skeleton/parameters", "properties": { "content": { - "description": "Source content to derive skeletons from. Mutually exclusive with `id`; exactly one of the two must be provided.\n", + "description": "Source ICU message string to derive skeletons from. Mutually exclusive with `id`; exactly one of the two must be provided.\n", "type": "string", - "example": "{number, plural, one {One} other {%{n}}}" + "example": "{count, plural, one {One item} other {# items}}" }, "id": { - "description": "Translation code to source content from. Mutually exclusive with `content`; exactly one of the two must be provided.\n", + "description": "Code of an existing translation to source content from. Mutually exclusive with `content`; exactly one of the two must be provided. Returns 404 when the translation does not exist.\n", "type": "string", "example": "abcd1234abcd1234abcd1234abcd1234" }, "locale_codes": { - "description": "Locale codes", + "description": "Locale codes for which to generate skeletons. The pluralization rules of each locale determine which plural forms appear in the output.\n", "type": "array", "items": { "type": "string", "example": "en" }, "example": [ - "en" + "en", + "de" ] }, "keep_content": { - "description": "Keep the content and add missing plural forms for each locale", + "description": "When true, preserves the existing translation text in each plural form and adds any missing forms for the locale rather than stripping all literal content.", "type": "boolean", - "example": null + "example": false }, "zero_form_enabled": { - "description": "Indicates whether the zero form should be included or excluded in the returned skeletons", + "description": "When true, includes the zero plural form in the generated skeleton for locales that support it.", "type": "boolean", - "example": null + "example": false }, "cldr_version": { - "description": "Strings supports two CLDR variants, when it comes to pluralization rules. \\\nYou can choose which one you want to use when constructing the skeletons. Possible values \\\nare `legacy` and `cldr_41`. Default value is `legacy`.", + "description": "Pluralization rule set to apply when constructing skeletons. Accepted values are `legacy` and `cldr_41`. Defaults to `legacy` when omitted.", "type": "string", + "enum": [ + "legacy", + "cldr_41" + ], "example": "cldr_41" } + }, + "oneOf": [ + { + "required": [ + "content" + ] + }, + { + "required": [ + "id" + ] + } + ] + } + } + } + }, + "responses": { + "200": { + "description": "OK", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icu" } } + }, + "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" + } } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "422": { + "description": "Unprocessable entity. Returned when the source string is not valid ICU message format syntax. The response body contains an `error` field with a human-readable description of the parse failure. Correct the ICU syntax in the source string and retry.", + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "icu/skeleton/error", + "properties": { + "error": { + "type": "string", + "description": "Human-readable description of the ICU message format parse failure.", + "example": "Expected \"#\" but \"x\" found." + } + } + } + } + } + }, + "429": { + "$ref": "#/components/responses/429" } }, "x-cli-version": "2.9" diff --git a/paths/icu/skeleton.yaml b/paths/icu/skeleton.yaml index 11b87eb0..830c0e13 100644 --- a/paths/icu/skeleton.yaml +++ b/paths/icu/skeleton.yaml @@ -1,46 +1,17 @@ --- summary: Build ICU skeletons -description: Returns ICU skeletons for multiple locale codes based on a source content. +description: | + Generates ICU (International Components for Unicode) message format skeletons for a given source string across one or more locales. An ICU skeleton strips the literal text from a pluralized or select message while preserving its structural rules — argument names, plural categories, select cases, and ordinal forms — adjusted to the pluralization rules of each requested locale. + + Use this endpoint to normalize translation templates before importing them into locale files, or to validate that a source string carries the plural forms required by a target language. + + Either `content` or `id` must be provided — supplying both or neither returns 400. When `id` is used and the referenced translation does not exist, the endpoint returns 404. When the source string is not valid ICU message format syntax, the endpoint returns 422 with an `error` field describing the parse failure. operationId: icu/skeleton tags: - ICU parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" -responses: - '200': - description: OK - content: - application/json: - schema: - "$ref": "../../schemas/icu.yaml#/skeleton" - 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" - Link: - "$ref": "../../headers.yaml#/Link" - '400': - "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" - '401': - "$ref": "../../responses.yaml#/401" - '403': - "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `read` scope. - '429': - "$ref": "../../responses.yaml#/429" x-code-samples: -- lang: Curl - source: |- - curl "https://api.phrase.com/v2/icu/skeleton" \ - -u USERNAME_OR_ACCESS_TOKEN \ - -X POST \ - -d '{"content":"{number, plural, one {One} other {%{n}}}","locale_codes":["en"],"zero_form_enabled": true}' \ - -H 'Content-Type: application/json' - lang: CLI v2 source: |- phrase icu skeleton \ @@ -55,37 +26,98 @@ requestBody: title: icu/skeleton/parameters properties: content: - description: | - Source content to derive skeletons from. Mutually exclusive with `id`; exactly one of the two must be provided. + description: > + Source ICU message string to derive skeletons from. Mutually + exclusive with `id`; exactly one of the two must be provided. type: string - example: "{number, plural, one {One} other {%{n}}}" + example: '{count, plural, one {One item} other {# items}}' id: - description: | - Translation code to source content from. Mutually exclusive with `content`; exactly one of the two must be provided. + description: > + Code of an existing translation to source content from. Mutually + exclusive with `content`; exactly one of the two must be + provided. Returns 404 when the translation does not exist. type: string example: abcd1234abcd1234abcd1234abcd1234 locale_codes: - description: Locale codes + description: > + Locale codes for which to generate skeletons. The pluralization + rules of each locale determine which plural forms appear in the + output. type: array items: type: string example: en example: - - en + - en + - de keep_content: - description: Keep the content and add missing plural forms for each locale + description: >- + When true, preserves the existing translation text in each + plural form and adds any missing forms for the locale rather + than stripping all literal content. type: boolean - example: + example: false zero_form_enabled: - description: Indicates whether the zero form should be included or excluded in the returned skeletons + description: >- + When true, includes the zero plural form in the generated + skeleton for locales that support it. type: boolean - example: + example: false cldr_version: - description: |- - Strings supports two CLDR variants, when it comes to pluralization rules. \ - You can choose which one you want to use when constructing the skeletons. Possible values \ - are `legacy` and `cldr_41`. Default value is `legacy`. + description: >- + Pluralization rule set to apply when constructing skeletons. + Accepted values are `legacy` and `cldr_41`. Defaults to + `legacy` when omitted. type: string + enum: + - legacy + - cldr_41 example: cldr_41 - + oneOf: + - required: + - content + - required: + - id +responses: + '200': + description: OK + content: + application/json: + schema: + "$ref": "../../schemas/icu.yaml#/skeleton" + 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" + Link: + "$ref": "../../headers.yaml#/Link" + '400': + "$ref": "../../responses.yaml#/400" + '401': + "$ref": "../../responses.yaml#/401" + '403': + "$ref": "../../responses.yaml#/403" + '404': + "$ref": "../../responses.yaml#/404" + '422': + description: >- + Unprocessable entity. Returned when the source string is not valid ICU + message format syntax. The response body contains an `error` field with + a human-readable description of the parse failure. Correct the ICU + syntax in the source string and retry. + content: + application/json: + schema: + type: object + title: icu/skeleton/error + properties: + error: + type: string + description: Human-readable description of the ICU message format parse failure. + example: "Expected \"#\" but \"x\" found." + '429': + "$ref": "../../responses.yaml#/429" x-cli-version: '2.9'