Skip to content

fix(API): improve post /icu/skeleton documentation #1187

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Stephen Lumenta (sbl) wants to merge 4 commits into
base: main
Choose a base branch
from
+173 −116
Open

fix(API): improve post /icu/skeleton documentation #1187

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a5f4fb1
feat(API): improve post /icu/skeleton documentation
sbl Jun 15, 2026
e4acc1c
fix(API): address review on post /icu/skeleton
sbl Jun 17, 2026
8e38a38
docs(API): move error-response prose to shared responses.yaml
sbl Jun 24, 2026
d753a2c
docs(API): remove hand-written x-code-samples
sbl Jun 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
146 changes: 87 additions & 59 deletions doc/compiled.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -5423,13 +5423,83 @@
"$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",
"content": {
"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 {}}"
}
}
},
Expand All @@ -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 <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"
Expand Down
143 changes: 86 additions & 57 deletions paths/icu/skeleton.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <token>
requestBody:
required: true
content:
Expand All @@ -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:
Comment thread
sbl marked this conversation as resolved.
- 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'
Loading