From a5f4fb138535d5d9b1f781c3f8eecd0505926ca8 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:52:58 +0200 Subject: [PATCH 1/2] feat(API): improve post /icu/skeleton documentation Sharper description explaining what ICU skeletons are and when to use the endpoint. Adds full parameter docs with descriptions and examples, promotes the requestBody schema to oneOf to document the content/id mutual-exclusion contract, documents all error responses (400, 401, 403, 404, 422, 429) with actionable remediation text, and updates the code samples to show realistic locale pairs and expected output. Resolves DEVEX-117. --- doc/compiled.json | 194 ++++++++++++++++++++++++---------- paths/icu/skeleton.yaml | 223 +++++++++++++++++++++++++++++++--------- 2 files changed, 315 insertions(+), 102 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..c8fb8f76 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,115 @@ "$ref": "#/components/parameters/X-PhraseApp-OTP" } ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "title": "icu/skeleton/parameters", + "oneOf": [ + { + "required": [ + "content" + ], + "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" + } + } + }, + { + "required": [ + "id" + ], + "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" + } + } + } + ] + } + } + } + }, "responses": { "200": { "description": "OK", @@ -5430,6 +5539,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 {}}" } } }, @@ -5449,81 +5562,54 @@ } }, "400": { + "description": "Bad request. Returned when both `content` and `id` are provided, when neither is provided, or when a parameter value cannot be parsed (for example, a non-boolean value for `keep_content`). Correct the request body so that exactly one of `content` or `id` is present with valid parameter types and retry.", "$ref": "#/components/responses/400" }, "401": { + "description": "Unauthorized. Returned when the request carries no valid access token or when a two-factor authentication code is required but absent or invalid. Provide a valid access token via the Authorization header or X-PhraseApp-OTP header and retry.", "$ref": "#/components/responses/401" }, "403": { - "$ref": "#/components/responses/403", - "description": "Forbidden. Returned when the access token lacks the `read` scope." + "description": "Forbidden. Returned when the access token lacks the `read` scope, or when the translation referenced by `id` is not visible to the authenticated user. Ensure the token has the `read` scope and that the authenticated user has access to the translation.", + "$ref": "#/components/responses/403" }, "404": { + "description": "Not found. Returned when the `id` parameter references a translation that does not exist. Verify the translation code and retry with a valid `id`, or switch to providing the source string directly via `content`.", "$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": { + "description": "Too many requests. Returned when the account's request rate limit or concurrency limit is exceeded. Wait until the time indicated by the `X-Rate-Limit-Reset` header before retrying.", "$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'" + "source": "curl \"https://api.phrase.com/v2/icu/skeleton\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"{count, plural, one {One item} other {# items}}\",\"locale_codes\":[\"en\",\"de\"],\"zero_form_enabled\":false}'\n\nExample response:\n{\n \"en\": \"{count, plural, offset:0 one {One item} other {# items}}\",\n \"de\": \"{count, plural, offset:0 one {} other {}}\"\n}" }, { "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 " + "source": "phrase icu skeleton \\\n--data '{\"content\":\"{count, plural, one {One item} other {# items}}\",\"locale_codes\":[\"en\",\"de\"],\"zero_form_enabled\":false}' \\\n--access_token \n\nExample response:\n{\n \"en\": \"{count, plural, offset:0 one {One item} other {# items}}\",\n \"de\": \"{count, plural, offset:0 one {} other {}}\"\n}" } ], - "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": { - "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" - } - } - } - } - } - }, "x-cli-version": "2.9" } }, diff --git a/paths/icu/skeleton.yaml b/paths/icu/skeleton.yaml index 11b87eb0..d907b20a 100644 --- a/paths/icu/skeleton.yaml +++ b/paths/icu/skeleton.yaml @@ -1,11 +1,126 @@ --- 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" +requestBody: + required: true + content: + application/json: + schema: + type: object + title: icu/skeleton/parameters + oneOf: + - required: + - content + properties: + content: + description: > + Source ICU message string to derive skeletons from. Mutually + exclusive with `id`; exactly one of the two must be provided. + 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. + 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. + 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 + - required: + - id + properties: + content: + description: > + Source ICU message string to derive skeletons from. Mutually + exclusive with `id`; exactly one of the two must be provided. + 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. + 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. + 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 responses: '200': description: OK @@ -13,6 +128,9 @@ responses: 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" @@ -23,15 +141,54 @@ responses: Link: "$ref": "../../headers.yaml#/Link" '400': + description: >- + Bad request. Returned when both `content` and `id` are provided, when + neither is provided, or when a parameter value cannot be parsed (for + example, a non-boolean value for `keep_content`). Correct the request + body so that exactly one of `content` or `id` is present with valid + parameter types and retry. "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" '401': + description: >- + Unauthorized. Returned when the request carries no valid access token or + when a two-factor authentication code is required but absent or invalid. + Provide a valid access token via the Authorization header or + X-PhraseApp-OTP header and retry. "$ref": "../../responses.yaml#/401" '403': + description: >- + Forbidden. Returned when the access token lacks the `read` scope, or + when the translation referenced by `id` is not visible to the + authenticated user. Ensure the token has the `read` scope and that + the authenticated user has access to the translation. "$ref": "../../responses.yaml#/403" - description: Forbidden. Returned when the access token lacks the `read` scope. + '404': + description: >- + Not found. Returned when the `id` parameter references a translation + that does not exist. Verify the translation code and retry with a valid + `id`, or switch to providing the source string directly via `content`. + "$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': + description: >- + Too many requests. Returned when the account's request rate limit or + concurrency limit is exceeded. Wait until the time indicated by the + `X-Rate-Limit-Reset` header before retrying. "$ref": "../../responses.yaml#/429" x-code-samples: - lang: Curl @@ -39,53 +196,23 @@ x-code-samples: 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' + -H "Content-Type: application/json" \ + -d '{"content":"{count, plural, one {One item} other {# items}}","locale_codes":["en","de"],"zero_form_enabled":false}' + + Example response: + { + "en": "{count, plural, offset:0 one {One item} other {# items}}", + "de": "{count, plural, offset:0 one {} other {}}" + } - lang: CLI v2 source: |- phrase icu skeleton \ - --data '{"content":"{number, plural, one {One} other {%{n}}}","locale_codes":["en"],"zero_form_enabled": true}' \ + --data '{"content":"{count, plural, one {One item} other {# items}}","locale_codes":["en","de"],"zero_form_enabled":false}' \ --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. - 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. - type: string - example: abcd1234abcd1234abcd1234abcd1234 - locale_codes: - description: Locale codes - type: array - items: - type: string - example: en - example: - - en - keep_content: - description: Keep the content and add missing plural forms for each locale - type: boolean - example: - zero_form_enabled: - description: Indicates whether the zero form should be included or excluded in the returned skeletons - type: boolean - example: - 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`. - type: string - example: cldr_41 + Example response: + { + "en": "{count, plural, offset:0 one {One item} other {# items}}", + "de": "{count, plural, offset:0 one {} other {}}" + } x-cli-version: '2.9' From e4acc1ca83bdcb3e36c09159a6a22565d5d463ad Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 20:52:06 +0100 Subject: [PATCH 2/2] fix(API): address review on post /icu/skeleton - Dedupe the requestBody schema: hoist the six shared properties to the top level and keep oneOf only to express the content-xor-id constraint (was repeating all six property definitions in both oneOf branches). - Drop the 'Example response' trailer from the curl and CLI v2 samples; the 200 example is already documented on the response, and no other endpoint inlines a response in its code sample. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 137 ++++++++++++---------------------- paths/icu/skeleton.yaml | 159 +++++++++++++--------------------------- 2 files changed, 96 insertions(+), 200 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index c8fb8f76..5dddeaf0 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5430,102 +5430,59 @@ "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" - ], - "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" - } - } + ] }, { "required": [ "id" - ], - "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" - } - } + ] } ] } @@ -5603,11 +5560,11 @@ "x-code-samples": [ { "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/icu/skeleton\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"{count, plural, one {One item} other {# items}}\",\"locale_codes\":[\"en\",\"de\"],\"zero_form_enabled\":false}'\n\nExample response:\n{\n \"en\": \"{count, plural, offset:0 one {One item} other {# items}}\",\n \"de\": \"{count, plural, offset:0 one {} other {}}\"\n}" + "source": "curl \"https://api.phrase.com/v2/icu/skeleton\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X POST \\\n -H \"Content-Type: application/json\" \\\n -d '{\"content\":\"{count, plural, one {One item} other {# items}}\",\"locale_codes\":[\"en\",\"de\"],\"zero_form_enabled\":false}'" }, { "lang": "CLI v2", - "source": "phrase icu skeleton \\\n--data '{\"content\":\"{count, plural, one {One item} other {# items}}\",\"locale_codes\":[\"en\",\"de\"],\"zero_form_enabled\":false}' \\\n--access_token \n\nExample response:\n{\n \"en\": \"{count, plural, offset:0 one {One item} other {# items}}\",\n \"de\": \"{count, plural, offset:0 one {} other {}}\"\n}" + "source": "phrase icu skeleton \\\n--data '{\"content\":\"{count, plural, one {One item} other {# items}}\",\"locale_codes\":[\"en\",\"de\"],\"zero_form_enabled\":false}' \\\n--access_token " } ], "x-cli-version": "2.9" diff --git a/paths/icu/skeleton.yaml b/paths/icu/skeleton.yaml index d907b20a..2b9af4fd 100644 --- a/paths/icu/skeleton.yaml +++ b/paths/icu/skeleton.yaml @@ -18,109 +18,60 @@ requestBody: 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. + 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. + 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. + 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 - properties: - content: - description: > - Source ICU message string to derive skeletons from. Mutually - exclusive with `id`; exactly one of the two must be provided. - 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. - 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. - 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 - required: - id - properties: - content: - description: > - Source ICU message string to derive skeletons from. Mutually - exclusive with `id`; exactly one of the two must be provided. - 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. - 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. - 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 responses: '200': description: OK @@ -198,21 +149,9 @@ x-code-samples: -X POST \ -H "Content-Type: application/json" \ -d '{"content":"{count, plural, one {One item} other {# items}}","locale_codes":["en","de"],"zero_form_enabled":false}' - - Example response: - { - "en": "{count, plural, offset:0 one {One item} other {# items}}", - "de": "{count, plural, offset:0 one {} other {}}" - } - lang: CLI v2 source: |- phrase icu skeleton \ --data '{"content":"{count, plural, one {One item} other {# items}}","locale_codes":["en","de"],"zero_form_enabled":false}' \ --access_token - - Example response: - { - "en": "{count, plural, offset:0 one {One item} other {# items}}", - "de": "{count, plural, offset:0 one {} other {}}" - } x-cli-version: '2.9'