diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..276cc803 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5413,7 +5413,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" @@ -5423,6 +5423,72 @@ "$ref": "#/components/parameters/X-PhraseApp-OTP" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "icu/skeleton/parameters", + "properties": { + "content": { + "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": "{count, plural, one {One item} other {# items}}" + }, + "id": { + "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 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", + "de" + ] + }, + "keep_content": { + "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": false + }, + "zero_form_enabled": { + "description": "When true, includes the zero plural form in the generated skeleton for locales that support it.", + "type": "boolean", + "example": false + }, + "cldr_version": { + "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", @@ -5430,6 +5496,10 @@ "application/json": { "schema": { "$ref": "#/components/schemas/icu" + }, + "example": { + "en": "{count, plural, offset:0 one {One item} other {# items}}", + "de": "{count, plural, offset:0 one {} other {}}" } } }, @@ -5455,73 +5525,31 @@ "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `read` scope." + "$ref": "#/components/responses/403" }, "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 " - } - ], - "requestBody": { - "required": true, - "content": { - "application/json": { - "schema": { - "type": "object", - "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", - "type": "string", - "example": "{number, plural, one {One} other {%{n}}}" - }, - "id": { - "description": "Translation code to source content from. Mutually exclusive with `content`; exactly one of the two must be provided.\n", - "type": "string", - "example": "abcd1234abcd1234abcd1234abcd1234" - }, - "locale_codes": { - "description": "Locale codes", - "type": "array", - "items": { + "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", - "example": "en" - }, - "example": [ - "en" - ] - }, - "keep_content": { - "description": "Keep the content and add missing plural forms for each locale", - "type": "boolean", - "example": null - }, - "zero_form_enabled": { - "description": "Indicates whether the zero form should be included or excluded in the returned skeletons", - "type": "boolean", - "example": null - }, - "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`.", - "type": "string", - "example": "cldr_41" + "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..59609aa1 100644 --- a/paths/icu/skeleton.yaml +++ b/paths/icu/skeleton.yaml @@ -1,51 +1,16 @@ --- 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 \ - --data '{"content":"{number, plural, one {One} other {%{n}}}","locale_codes":["en"],"zero_form_enabled": true}' \ - --access_token requestBody: required: true content: @@ -55,37 +20,101 @@ 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" + example: + en: '{count, plural, offset:0 one {One item} other {# items}}' + de: '{count, plural, offset:0 one {} other {}}' + 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'