From 99487ab350e06eeaa5d6df8134c269b974995586 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Sun, 21 Jun 2026 22:00:46 -0400 Subject: [PATCH 1/8] TCM-6557 Align strings-api-v2.yaml with internal spec - Rename path parameter {projectId} to {projectUid} across all four strings-api paths (both path keys in openapi.yaml and parameter names in the spec file) - Add strings.maxItems: 100 and fix strings.items.maxLength type number -> integer in the create endpoint - Add uri and authorization fields to the create strings request body - Add showPlaceholderValues parameter to source-strings and translations endpoints (GET params and POST body) - Raise translations limit maximum from 500 to 10,000 Co-Authored-By: Claude Sonnet 4.6 (1M context) --- spec/openapi.yaml | 8 +- spec/strings/strings-api-v2.yaml | 125 +++++++++++++++++++------------ 2 files changed, 82 insertions(+), 51 deletions(-) diff --git a/spec/openapi.yaml b/spec/openapi.yaml index dec77d0a..0ba63d3c 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -4205,16 +4205,16 @@ paths: # # Strings API # - '/strings-api/v2/projects/{projectId}': + '/strings-api/v2/projects/{projectUid}': $ref: './spec/strings/strings-api-v2.yaml#/x-paths/add_strings' - '/strings-api/v2/projects/{projectId}/processes/{processUid}': + '/strings-api/v2/projects/{projectUid}/processes/{processUid}': $ref: './spec/strings/strings-api-v2.yaml#/x-paths/check_string_status' - '/strings-api/v2/projects/{projectId}/source-strings': + '/strings-api/v2/projects/{projectUid}/source-strings': $ref: './spec/strings/strings-api-v2.yaml#/x-paths/source_strings' - '/strings-api/v2/projects/{projectId}/translations': + '/strings-api/v2/projects/{projectUid}/translations': $ref: './spec/strings/strings-api-v2.yaml#/x-paths/translations' # diff --git a/spec/strings/strings-api-v2.yaml b/spec/strings/strings-api-v2.yaml index d99ba89f..416e4b4c 100644 --- a/spec/strings/strings-api-v2.yaml +++ b/spec/strings/strings-api-v2.yaml @@ -42,18 +42,13 @@ x-paths: operationId: addStringsToProject parameters: - - in: path - name: projectId - required: true - schema: - format: uuid - type: string + - $ref: '#/components/parameters/projectUid' requestBody: content: application/json: schema: properties: - strings (Required): + strings: items: properties: stringText: @@ -87,7 +82,7 @@ x-paths: string and its translations. Not specifying or setting to 'null' implies no maxLength and on update will remove any existing maxLegnth. - type: number + type: integer format: description: >- Sets whether or not the string should be parsed as @@ -108,6 +103,7 @@ x-paths: - stringText type: object minItems: 1 + maxItems: 100 type: array placeholderFormat: description: >- @@ -136,6 +132,35 @@ x-paths: _smartling.strings-api.default.namespace_. A _NULL_ value is permitted. type: string + uri: + description: >- + Virtual file URI to associate with these strings. + Defaults to `/Strings` when not provided. + type: string + authorization: + description: >- + When provided, simultaneously authorizes the created strings + into translation workflows. + type: object + properties: + localeWorkflows: + description: Locale and workflow pairs to authorize the strings into. + type: array + items: + type: object + required: + - targetLocaleId + - workflowUid + properties: + targetLocaleId: + type: string + description: Target locale identifier. + workflowUid: + type: string + description: Workflow unique identifier. + translationJobUid: + type: string + description: UID of an existing translation job to add the strings to. type: object required: - strings @@ -205,12 +230,7 @@ x-paths: operationId: getAddStringsToProjectRequestStatus parameters: - - in: path - name: projectId - required: true - schema: - format: uuid - type: string + - $ref: '#/components/parameters/projectUid' - in: path name: processUid required: true @@ -267,12 +287,7 @@ x-paths: - Strings operationId: getAllSourceStringsByProject parameters: - - in: path - name: projectId - required: true - schema: - format: uuid - type: string + - $ref: '#/components/parameters/projectUid' - description: Hashcodes for each string you want to get source strings for. in: query name: hashcodes @@ -291,12 +306,13 @@ x-paths: in: query name: limit schema: - type: number + type: integer - description: Pagination setting. Default is 0. in: query name: offset schema: - type: number + type: integer + - $ref: '#/components/parameters/showPlaceholderValues' responses: '200': content: @@ -347,12 +363,7 @@ x-paths: - Strings operationId: getAllSourceStringsByProjectPost parameters: - - in: path - name: projectId - required: true - schema: - format: uuid - type: string + - $ref: '#/components/parameters/projectUid' requestBody: required: true content: @@ -372,10 +383,12 @@ x-paths: description: >- By default, responses will be limited to 500 per request. This is also the maximum allowed value. - type: number + type: integer offset: description: Pagination setting. Default is 0. - type: number + type: integer + showPlaceholderValues: + $ref: '#/components/parameters/showPlaceholderValues' responses: '200': content: @@ -431,12 +444,7 @@ x-paths: - Strings operationId: getAllTranslationsByProject parameters: - - description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API. - in: path - name: projectId - required: true - schema: - type: string + - $ref: '#/components/parameters/projectUid' - description: Hashcodes for each string you want to get translations for. in: query name: hashcodes @@ -468,16 +476,19 @@ x-paths: type: string - description: >- Pagination setting. By default, responses will be limited to 500 per - request. This is also the maximum allowed value. + request. Maximum allowed value is 10,000. in: query name: limit schema: - type: number + type: integer + maximum: 10000 + default: 500 - description: Pagination setting. Default is 0. in: query name: offset schema: - type: number + type: integer + - $ref: '#/components/parameters/showPlaceholderValues' responses: '200': content: @@ -531,12 +542,7 @@ x-paths: - Strings operationId: getAllTranslationsByProjectPost parameters: - - description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API. - in: path - name: projectId - required: true - schema: - type: string + - $ref: '#/components/parameters/projectUid' requestBody: required: true content: @@ -570,10 +576,14 @@ x-paths: description: >- Pagination setting. By default, responses will be limited to 500 per request. This is also the maximum allowed value. - type: number + type: integer + maximum: 500 + default: 500 offset: description: Pagination setting. Default is 0. - type: number + type: integer + showPlaceholderValues: + $ref: '#/components/parameters/showPlaceholderValues' responses: '200': content: @@ -595,3 +605,24 @@ x-paths: curl -H "Authorization: Bearer $smartlingToken" -H "Content-Type: application/json" -d '{"targetLocaleId": "es", "fileUri": "$smartlingFileUri"}' https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId/translations + +components: + parameters: + projectUid: + name: projectUid + in: path + required: true + description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API. + schema: + type: string + format: uuid + showPlaceholderValues: + name: showPlaceholderValues + in: query + description: >- + When `true` (default), placeholder tokens are resolved to display + values. When `false`, internal placeholder format (`{0}`, `{1}`, etc.) + is preserved. + schema: + type: boolean + default: true From c31142288df44e596ec6140ce7f7b2046b7f99b2 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Mon, 22 Jun 2026 10:16:24 -0400 Subject: [PATCH 2/8] Added claude.md --- CLAUDE.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..73021dab --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,47 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repo is + +OpenAPI 3.0 specification for the Smartling REST API, published at https://api-reference.smartling.com/. The spec is split across multiple YAML files under `spec/` and bundled at build time into a single `swagger.json`/`swagger.yaml` for rendering via ReDoc/Swagger UI. + +## Commands + +```bash +npm install # install dependencies (Node 17+ required) +npm start # build, start local server + swagger-editor (live reload) +npm test # validate the OpenAPI spec (swagger-repo validate) +npm run build # bundle spec into web_deploy/ +npm run process-yaml # re-generate TQC x-paths (required after editing TQC YAML files) +``` + +The local server URL is printed to console on startup. The swagger-editor URL is also printed separately (port 5000+). + +## Spec structure + +- `spec/openapi.yaml` - root file: server, global tags (with long descriptions), and `$ref` paths to all sub-specs +- `spec/api_common.yaml` - shared reusable components: parameters (`accountUid`, `projectId`, `localeId`), request bodies, and common schemas (`SuccessResponse`, `EmptyResponse`, etc.) +- Each API domain lives in its own subdirectory: + - `spec/translation_quality/` - TQC endpoints split across many files; uses `x-paths` extension and requires `npm run process-yaml` after edits + - `spec/issues/` - Issues, issue comments, watchers, dictionaries, sub-types + - `spec/job_batches_v1/` and `spec/job_batches_v2/` - Job batch endpoints + - `spec/glossary_v3/` - Glossary, blocklist, import/export, labels, entries + - `spec/webhooks_api/` - Webhook subscriptions, events, components + - `spec/file_translation/` - File MT upload, MT, language detection + - `spec/strings/` - Strings API v2 (uses `x-paths` extension) + - `spec/connectors_import_v3/` - Connectors Import API + +## Key conventions + +**Global headers**: The `headers:` top-level key (non-standard) is supported - references like `$ref: "#/headers/Rate-Limit-Limit"` are inlined and the `headers` block is removed during build so the output remains valid OpenAPI. + +**x-paths extension**: `spec/translation_quality/` and `spec/strings/` use a custom `x-paths` key (not the standard `paths`) with `$ref` includes. Running `npm run process-yaml` resolves these refs and merges them into `spec/openapi.yaml`. Always run this after editing TQC or Strings YAML files. + +**Build output**: `npm run build` produces `web_deploy/` containing the bundled spec (`swagger.json`, `swagger.yaml`), the static web UI, and copies of all spec subdirectories. + +## CI/CD + +- Jenkins builds on every branch; non-master branches deploy a preview at `https://api-reference.smartling.com/preview/` +- `master` deploys to the main documentation site +- Preview branches are not auto-cleaned; stale previews must be cleaned manually via the `gh-pages` branch (see README.md) From c5bab9ef434923a2aef5a3089de51613c6bc48b1 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Mon, 22 Jun 2026 10:50:55 -0400 Subject: [PATCH 3/8] TCM-6557 Add LocaleId schema and improve parameter examples - Extract LocaleId as a reusable schema in api_common.yaml with type, pattern, and description - Update localeId parameter to reference LocaleId schema and add named examples with summaries - Add summary to projectId example to fix trailing dash in rendered output - Update targetLocaleId fields in strings-api-v2.yaml to reference LocaleId schema Co-Authored-By: Claude Sonnet 4.6 (1M context) --- spec/api_common.yaml | 90 ++++++++++++++++++++++++- spec/strings/strings-api-v2.yaml | 109 ++++++++++++------------------- 2 files changed, 130 insertions(+), 69 deletions(-) diff --git a/spec/api_common.yaml b/spec/api_common.yaml index 82d4fd71..63a6419f 100644 --- a/spec/api_common.yaml +++ b/spec/api_common.yaml @@ -11,15 +11,49 @@ components: name: projectId in: path required: true - type: string description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API. + schema: + type: string + pattern: '^[a-z0-9]{9}$' + examples: + typical: + summary: Typical project ID + value: abcd12345 localeId: name: localeId in: path required: true - type: string - description: A valid Smartling Locale ID. + description: | + Locale identifier. Either a 2-letter language code (`en`) or a + language-region pair (`en-US`). The language part is always lowercase; + the region part is always uppercase. + schema: + $ref: '#/components/schemas/LocaleId' + examples: + language_only: + summary: Language code only + value: en + language_region: + summary: Language and region + value: fr-FR + + offset: + name: offset + in: query + description: Number of items to skip. Default is 0. + schema: + type: integer + minimum: 0 + default: 0 + + limit: + name: limit + in: query + description: Maximum number of items to return per page. + schema: + type: integer + minimum: 1 requestBodies: @@ -41,6 +75,56 @@ components: schemas: + DateTime: + type: string + format: date-time + description: ISO 8601 UTC timestamp. + examples: + - "2026-01-15T10:00:00Z" + + FileUri: + type: string + description: URI path of a source file within a Smartling project. + examples: + - /content/en/home.json + + LocaleId: + type: string + pattern: '^[a-z]{2}(-[A-Z]{2})?$' + description: | + Locale identifier. Either a 2-letter language code (`en`) or a + language-region pair (`en-US`). The language part is always lowercase; + the region part is always uppercase. + example: fr-FR + + Hashcode: + type: string + description: MD5 hash digest — 32 lowercase hexadecimal characters. + pattern: '^[a-f0-9]{32}$' + examples: + - d41d8cd98f00b204e9800998ecf8427e + + TranslationJobUid: + type: string + description: Translation job unique identifier — 12 lowercase alphanumeric characters. + pattern: '^[a-z0-9]{12}$' + examples: + - j45v1uvsi3tx + + WorkflowUid: + type: string + description: Workflow unique identifier — 12 lowercase alphanumeric characters. + pattern: '^[a-z0-9]{12}$' + examples: + - 5449a8595ae4 + + WorkflowStepUid: + type: string + description: Workflow step unique identifier — 12 lowercase alphanumeric characters. + pattern: '^[a-z0-9]{12}$' + examples: + - 7564fc097a85 + SuccessResponse: type: object required: diff --git a/spec/strings/strings-api-v2.yaml b/spec/strings/strings-api-v2.yaml index 416e4b4c..636de605 100644 --- a/spec/strings/strings-api-v2.yaml +++ b/spec/strings/strings-api-v2.yaml @@ -12,11 +12,6 @@ x-paths: will return an error. Each string has a character limit of 10,000. - **Note**: You cannot authorize a string via API. Once you have created - the strings, they will need to be authorized by a content owner in the - Smartling Dashboard. - - Smartling creates a unique hashcode for each string based on the parsed string text and any variant or namespace metadata provided. If you upload a string with the same text, variant and namespace, and therefore @@ -42,7 +37,7 @@ x-paths: operationId: addStringsToProject parameters: - - $ref: '#/components/parameters/projectUid' + - $ref: '../api_common.yaml#/components/parameters/projectId' requestBody: content: application/json: @@ -136,7 +131,8 @@ x-paths: description: >- Virtual file URI to associate with these strings. Defaults to `/Strings` when not provided. - type: string + allOf: + - $ref: '../api_common.yaml#/components/schemas/FileUri' authorization: description: >- When provided, simultaneously authorizes the created strings @@ -153,14 +149,11 @@ x-paths: - workflowUid properties: targetLocaleId: - type: string - description: Target locale identifier. + $ref: '../api_common.yaml#/components/schemas/LocaleId' workflowUid: - type: string - description: Workflow unique identifier. + $ref: '../api_common.yaml#/components/schemas/WorkflowUid' translationJobUid: - type: string - description: UID of an existing translation job to add the strings to. + $ref: '../api_common.yaml#/components/schemas/TranslationJobUid' type: object required: - strings @@ -230,7 +223,7 @@ x-paths: operationId: getAddStringsToProjectRequestStatus parameters: - - $ref: '#/components/parameters/projectUid' + - $ref: '../api_common.yaml#/components/parameters/projectId' - in: path name: processUid required: true @@ -287,19 +280,19 @@ x-paths: - Strings operationId: getAllSourceStringsByProject parameters: - - $ref: '#/components/parameters/projectUid' + - $ref: '../api_common.yaml#/components/parameters/projectId' - description: Hashcodes for each string you want to get source strings for. in: query name: hashcodes schema: items: - type: string + $ref: '../api_common.yaml#/components/schemas/Hashcode' type: array - description: URI of a file you want to get strings for. in: query name: fileUri schema: - type: string + $ref: '../api_common.yaml#/components/schemas/FileUri' - description: >- By default, responses will be limited to 500 per request. This is also the maximum allowed value. @@ -307,11 +300,7 @@ x-paths: name: limit schema: type: integer - - description: Pagination setting. Default is 0. - in: query - name: offset - schema: - type: integer + - $ref: '../api_common.yaml#/components/parameters/offset' - $ref: '#/components/parameters/showPlaceholderValues' responses: '200': @@ -363,7 +352,7 @@ x-paths: - Strings operationId: getAllSourceStringsByProjectPost parameters: - - $ref: '#/components/parameters/projectUid' + - $ref: '../api_common.yaml#/components/parameters/projectId' requestBody: required: true content: @@ -375,10 +364,9 @@ x-paths: description: Hashcodes for each string you want to get source strings for. type: array items: - type: string + $ref: '../api_common.yaml#/components/schemas/Hashcode' fileUri: - description: URI of a file you want to get strings for. - type: string + $ref: '../api_common.yaml#/components/schemas/FileUri' limit: description: >- By default, responses will be limited to 500 per request. This is @@ -388,7 +376,7 @@ x-paths: description: Pagination setting. Default is 0. type: integer showPlaceholderValues: - $ref: '#/components/parameters/showPlaceholderValues' + $ref: '#/components/schemas/ShowPlaceholderValues' responses: '200': content: @@ -444,20 +432,20 @@ x-paths: - Strings operationId: getAllTranslationsByProject parameters: - - $ref: '#/components/parameters/projectUid' + - $ref: '../api_common.yaml#/components/parameters/projectId' - description: Hashcodes for each string you want to get translations for. in: query name: hashcodes schema: items: - type: string + $ref: '../api_common.yaml#/components/schemas/Hashcode' type: array - description: Smartling ID for the language you want to get translations for. in: query name: targetLocaleId required: true schema: - type: string + $ref: '../api_common.yaml#/components/schemas/LocaleId' - description: >- Sets the types of translations you want returned. `published` will only return translations that have completed their workflows and @@ -473,21 +461,15 @@ x-paths: in: query name: fileUri schema: - type: string + $ref: '../api_common.yaml#/components/schemas/FileUri' - description: >- Pagination setting. By default, responses will be limited to 500 per request. Maximum allowed value is 10,000. in: query name: limit schema: - type: integer - maximum: 10000 - default: 500 - - description: Pagination setting. Default is 0. - in: query - name: offset - schema: - type: integer + $ref: '#/components/schemas/TranslationsLimit' + - $ref: '../api_common.yaml#/components/parameters/offset' - $ref: '#/components/parameters/showPlaceholderValues' responses: '200': @@ -542,7 +524,7 @@ x-paths: - Strings operationId: getAllTranslationsByProjectPost parameters: - - $ref: '#/components/parameters/projectUid' + - $ref: '../api_common.yaml#/components/parameters/projectId' requestBody: required: true content: @@ -556,10 +538,9 @@ x-paths: description: Hashcodes for each string you want to get translations for. type: array items: - type: string + $ref: '../api_common.yaml#/components/schemas/Hashcode' targetLocaleId: - description: Smartling ID for the language you want to get translations for. - type: string + $ref: '../api_common.yaml#/components/schemas/LocaleId' retrievalType: description: >- Sets the types of translations you want returned. `published` will @@ -570,20 +551,14 @@ x-paths: - pending - published fileUri: - description: URI of a file you want to get translations for. - type: string + $ref: '../api_common.yaml#/components/schemas/FileUri' limit: - description: >- - Pagination setting. By default, responses will be limited to 500 per - request. This is also the maximum allowed value. - type: integer - maximum: 500 - default: 500 + $ref: '#/components/schemas/TranslationsLimit' offset: description: Pagination setting. Default is 0. type: integer showPlaceholderValues: - $ref: '#/components/parameters/showPlaceholderValues' + $ref: '#/components/schemas/ShowPlaceholderValues' responses: '200': content: @@ -607,22 +582,24 @@ x-paths: https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId/translations components: - parameters: - projectUid: - name: projectUid - in: path - required: true - description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API. - schema: - type: string - format: uuid - showPlaceholderValues: - name: showPlaceholderValues - in: query + schemas: + TranslationsLimit: + description: >- + Pagination setting. By default, responses will be limited to 500 per + request. Maximum allowed value is 10,000. + type: integer + maximum: 10000 + default: 500 + ShowPlaceholderValues: description: >- When `true` (default), placeholder tokens are resolved to display values. When `false`, internal placeholder format (`{0}`, `{1}`, etc.) is preserved. + type: boolean + default: true + parameters: + showPlaceholderValues: + name: showPlaceholderValues + in: query schema: - type: boolean - default: true + $ref: '#/components/schemas/ShowPlaceholderValues' From 34688e3232995e9712e377933f05f671dc43cfa9 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Tue, 23 Jun 2026 18:43:58 -0400 Subject: [PATCH 4/8] TCM-6557 Move strings-api schemas from openapi.yaml to strings-api-v2.yaml Move CreateStringResponse, CreateStringStatusResponse, CreatedString, StringInfo, StringResponse, Translation, and TranslationResponse schemas to strings-api-v2.yaml since they are only used by the Strings API. Co-Authored-By: Claude Sonnet 4.6 (1M context) --- spec/openapi.yaml | 255 ------------------------------- spec/strings/strings-api-v2.yaml | 255 +++++++++++++++++++++++++++++++ 2 files changed, 255 insertions(+), 255 deletions(-) diff --git a/spec/openapi.yaml b/spec/openapi.yaml index 0ba63d3c..92df2af7 100644 --- a/spec/openapi.yaml +++ b/spec/openapi.yaml @@ -10504,111 +10504,6 @@ components: type: string description: GraphQL type name example: "StringGroup" - CreateStringResponse: - type: object - required: - - response - properties: - response: - allOf: - - $ref: '#/components/schemas/SuccessResponse' - - properties: - data: - properties: - items: - items: - $ref: '#/components/schemas/CreatedString' - type: array - processUid: - description: >- - If the request takes longer than 60 seconds to process, a - `202` response will be returned, indicating the request has - not failed, but is not yet complete. Use the processUid - value to check the status of the request using the Check - Create String Status request. - type: string - stringCount: - description: Total number of strings captured as a result of the request. - type: number - totalCount: - type: number - wordCount: - description: Total number of words captured as a result of the request. - type: number - type: object - type: object - CreateStringStatusResponse: - type: object - required: - - response - properties: - response: - allOf: - - $ref: '#/components/schemas/SuccessResponse' - - properties: - data: - properties: - createdDate: - description: Total number of strings captured as a result of the request. - type: string - modifiedDate: - description: >- - If the request takes longer than 60 seconds to process, a - `202` response will be returned, indicating the request has - not failed, but is not yet complete. Use the processUid - value to check the status of the request using the Check - Create String Status request. - type: string - processState: - description: State of the request - enum: - - OPEN - - CLOSED - - FAILED - type: string - processStatistics: - description: Information on the created or updated string - properties: - errored: - description: strings that had errors - type: string - processed: - description: strings processed - type: string - requested: - description: strings requested - type: string - skipped: - description: strings skipped - type: string - type: object - processUid: - description: Unique identifer for a create string request. - type: string - type: object - type: object - CreatedString: - description: Information on the created or updated string - properties: - hashcode: - description: The generated unique idenitfier for this created or updated string. - type: string - overWritten: - description: Idenitfies if the string was already in the system. - type: string - parsedStringText: - description: >- - The text for this string used to define its uniqueness in the - Smartling system. This is after placeholders have been processed - and escaping normalization has been applied. - type: string - stringText: - description: The text for this string - type: string - variant: - description: String variant - type: string - type: object LocaleHashcodeResponse: type: object required: @@ -12864,81 +12759,6 @@ components: description: The total number of words within that particular step. type: number type: object - StringInfo: - description: Information on string - properties: - hashcode: - description: The generated unique idenitfier for this created or updated string. - type: string - keys: - description: >- - If this string is associated with one or more resource files this is - a list of the associated resource keys. - items: - properties: - fileUri: - description: resource key - type: string - key: - description: fileUri of the key - type: string - type: object - type: array - parsedStringText: - description: >- - The text for this string used to define its uniqueness in the - Smartling system. This is after placeholders have been processed - and escaping normalization has been applied. - type: string - stringText: - description: The text for this string - type: string - stringVariant: - description: String variant - type: string - maxLength: - description: Maximum character length - type: number - stringInstructions: - description: >- - String instructions that were added to the string in the Dashboard. - items: - description: The text of the instruction. - type: string - type: array - contentFileStringInstructions: - description: >- - String instructions that were included in the uploaded file if any. - items: - properties: - fileUri: - description: URI of the file that contained the instruction. - type: string - contentFileStringInstruction: - description: The text of the instruction. - type: string - type: object - type: array - type: object - StringResponse: - type: object - required: - - response - properties: - response: - allOf: - - $ref: '#/components/schemas/SuccessResponse' - - properties: - data: - properties: - items: - items: - $ref: '#/components/schemas/StringInfo' - type: array - totalCount: - type: number - type: object - type: object SuccessFailCountJobResponse: type: object required: @@ -13070,81 +12890,6 @@ components: format: int64 type: integer type: object - Translation: - description: Information on a translation - properties: - hashcode: - description: The generated unique idenitfier for this created or updated string. - type: string - keys: - description: >- - If this string is associated with one or more resource files this is - a list of the associated resource keys. - items: - properties: - fileUri: - description: resource key - type: string - key: - description: fileUri of the key - type: string - type: object - type: array - parsedStringText: - description: >- - The text for this string used to define its uniqueness in the - Smartling system. This is after placeholders have been processed - and escaping normalization has been applied. - type: string - stringText: - description: The text for this string. - type: string - targetLocaleId: - description: Locale ID of this translation - type: string - translations: - items: - properties: - modifiedDate: - description: When this translation was last modified. - type: string - pluralForm: - description: >- - Pural form of the translation. `null` if this translation is - not a plural. - type: string - translation: - description: Translation text - type: string - type: object - type: array - stringVariant: - description: String variant - type: string - workflowStepUid: - description: Current workflow step for this translation - format: uuid - type: string - type: object - TranslationResponse: - type: object - required: - - response - properties: - response: - allOf: - - $ref: '#/components/schemas/SuccessResponse' - - properties: - data: - properties: - items: - items: - $ref: '#/components/schemas/Translation' - type: array - totalCount: - type: number - type: object - type: object UpdateJobRequest: description: The payload to use when updating a job. properties: diff --git a/spec/strings/strings-api-v2.yaml b/spec/strings/strings-api-v2.yaml index 636de605..dddaa83f 100644 --- a/spec/strings/strings-api-v2.yaml +++ b/spec/strings/strings-api-v2.yaml @@ -597,6 +597,261 @@ components: is preserved. type: boolean default: true + CreateStringResponse: + type: object + required: + - response + properties: + response: + allOf: + - $ref: '../api_common.yaml#/components/schemas/SuccessResponse' + - properties: + data: + properties: + items: + items: + $ref: '#/components/schemas/CreatedString' + type: array + processUid: + description: >- + If the request takes longer than 60 seconds to process, a + `202` response will be returned, indicating the request has + not failed, but is not yet complete. Use the processUid + value to check the status of the request using the Check + Create String Status request. + type: string + stringCount: + description: Total number of strings captured as a result of the request. + type: number + totalCount: + type: number + wordCount: + description: Total number of words captured as a result of the request. + type: number + type: object + type: object + CreateStringStatusResponse: + type: object + required: + - response + properties: + response: + allOf: + - $ref: '../api_common.yaml#/components/schemas/SuccessResponse' + - properties: + data: + properties: + createdDate: + description: Total number of strings captured as a result of the request. + type: string + modifiedDate: + description: >- + If the request takes longer than 60 seconds to process, a + `202` response will be returned, indicating the request has + not failed, but is not yet complete. Use the processUid + value to check the status of the request using the Check + Create String Status request. + type: string + processState: + description: State of the request + enum: + - OPEN + - CLOSED + - FAILED + type: string + processStatistics: + description: Information on the created or updated string + properties: + errored: + description: strings that had errors + type: string + processed: + description: strings processed + type: string + requested: + description: strings requested + type: string + skipped: + description: strings skipped + type: string + type: object + processUid: + description: Unique identifer for a create string request. + type: string + type: object + type: object + CreatedString: + description: Information on the created or updated string + properties: + hashcode: + description: The generated unique idenitfier for this created or updated string. + type: string + overWritten: + description: Idenitfies if the string was already in the system. + type: string + parsedStringText: + description: >- + The text for this string used to define its uniqueness in the + Smartling system. This is after placeholders have been processed + and escaping normalization has been applied. + type: string + stringText: + description: The text for this string + type: string + variant: + description: String variant + type: string + type: object + StringInfo: + description: Information on string + properties: + hashcode: + description: The generated unique idenitfier for this created or updated string. + type: string + keys: + description: >- + If this string is associated with one or more resource files this is + a list of the associated resource keys. + items: + properties: + fileUri: + description: resource key + type: string + key: + description: fileUri of the key + type: string + type: object + type: array + parsedStringText: + description: >- + The text for this string used to define its uniqueness in the + Smartling system. This is after placeholders have been processed + and escaping normalization has been applied. + type: string + stringText: + description: The text for this string + type: string + stringVariant: + description: String variant + type: string + maxLength: + description: Maximum character length + type: number + stringInstructions: + description: >- + String instructions that were added to the string in the Dashboard. + items: + description: The text of the instruction. + type: string + type: array + contentFileStringInstructions: + description: >- + String instructions that were included in the uploaded file if any. + items: + properties: + fileUri: + description: URI of the file that contained the instruction. + type: string + contentFileStringInstruction: + description: The text of the instruction. + type: string + type: object + type: array + type: object + StringResponse: + type: object + required: + - response + properties: + response: + allOf: + - $ref: '../api_common.yaml#/components/schemas/SuccessResponse' + - properties: + data: + properties: + items: + items: + $ref: '#/components/schemas/StringInfo' + type: array + totalCount: + type: number + type: object + type: object + Translation: + description: Information on a translation + properties: + hashcode: + description: The generated unique idenitfier for this created or updated string. + type: string + keys: + description: >- + If this string is associated with one or more resource files this is + a list of the associated resource keys. + items: + properties: + fileUri: + description: resource key + type: string + key: + description: fileUri of the key + type: string + type: object + type: array + parsedStringText: + description: >- + The text for this string used to define its uniqueness in the + Smartling system. This is after placeholders have been processed + and escaping normalization has been applied. + type: string + stringText: + description: The text for this string. + type: string + targetLocaleId: + description: Locale ID of this translation + type: string + translations: + items: + properties: + modifiedDate: + description: When this translation was last modified. + type: string + pluralForm: + description: >- + Pural form of the translation. `null` if this translation is + not a plural. + type: string + translation: + description: Translation text + type: string + type: object + type: array + stringVariant: + description: String variant + type: string + workflowStepUid: + description: Current workflow step for this translation + format: uuid + type: string + type: object + TranslationResponse: + type: object + required: + - response + properties: + response: + allOf: + - $ref: '../api_common.yaml#/components/schemas/SuccessResponse' + - properties: + data: + properties: + items: + items: + $ref: '#/components/schemas/Translation' + type: array + totalCount: + type: number + type: object + type: object parameters: showPlaceholderValues: name: showPlaceholderValues From 7b67d12097b1f06fafbb560cc21df031ddba62e5 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Tue, 23 Jun 2026 18:49:44 -0400 Subject: [PATCH 5/8] TCM-6557 Fix swapped descriptions for fileUri/key and clarify key nullability Co-Authored-By: Claude Sonnet 4.6 (1M context) Claude-Session: https://claude.ai/code/session_01EVm9PgBYifHQd5yjAKq32p --- spec/strings/strings-api-v2.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/strings/strings-api-v2.yaml b/spec/strings/strings-api-v2.yaml index dddaa83f..e52e00a3 100644 --- a/spec/strings/strings-api-v2.yaml +++ b/spec/strings/strings-api-v2.yaml @@ -715,10 +715,10 @@ components: items: properties: fileUri: - description: resource key + description: fileUri of the key type: string key: - description: fileUri of the key + description: Resource key. `null` if the string does not have a variant. type: string type: object type: array @@ -790,10 +790,10 @@ components: items: properties: fileUri: - description: resource key + description: fileUri of the key type: string key: - description: fileUri of the key + description: Resource key. `null` if the string does not have a variant. type: string type: object type: array From 063e569507f7b90777e94347c28df645ddedc4d7 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Tue, 23 Jun 2026 19:04:15 -0400 Subject: [PATCH 6/8] TCM-6557 Fix missing spec/strings copy in branch preview deployment Co-Authored-By: Claude Sonnet 4.6 (1M context) Claude-Session: https://claude.ai/code/session_01EVm9PgBYifHQd5yjAKq32p --- scripts/deploy-branch.js | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/deploy-branch.js b/scripts/deploy-branch.js index 49329035..b698fd18 100644 --- a/scripts/deploy-branch.js +++ b/scripts/deploy-branch.js @@ -23,6 +23,7 @@ if (branch && branch !== 'gh-pages') { cp('-R', 'spec/connectors_import_v3', specFolder); cp('-R', 'spec/glossary_v3', specFolder); cp('-R', 'spec/webhooks_api', specFolder); + cp('-R', 'spec/strings', specFolder); cp('-R', 'spec/api_common.yaml', specFolder); exec('deploy-to-gh-pages --update .tmp'); From f11c77ddf7e03dcd52187b276b67a460e4a846f7 Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Wed, 24 Jun 2026 09:48:29 -0400 Subject: [PATCH 7/8] TCM-6557 Fix typos and improve descriptions in strings-api-v2.yaml Co-Authored-By: Claude Sonnet 4.6 (1M context) --- spec/strings/strings-api-v2.yaml | 41 ++++++++++++++------------------ 1 file changed, 18 insertions(+), 23 deletions(-) diff --git a/spec/strings/strings-api-v2.yaml b/spec/strings/strings-api-v2.yaml index e52e00a3..511d45cf 100644 --- a/spec/strings/strings-api-v2.yaml +++ b/spec/strings/strings-api-v2.yaml @@ -15,17 +15,17 @@ x-paths: Smartling creates a unique hashcode for each string based on the parsed string text and any variant or namespace metadata provided. If you upload a string with the same text, variant and namespace, and therefore - the same hashcode, the existng string will be overwritten. This will not + the same hashcode, the existing string will be overwritten. This will not change the text of the string, but may update other metadata, such as placeholder and callback values. If the string is currently inactive, - overwriting it will cause it to be reactivated. Overwritten strings + overwriting it will reactivate it. Overwritten strings return `"overWritten": "true"` in the response object. Most uploads will return a `200` response indicating success. If - processing the request takes longer than 60 seconds, a `202` request + processing the request takes longer than 60 seconds, a `202` response will be returned, including a `processUid` value that can be used to - check on the progress of the request. + check the progress of the request. If you set up a POST callback for the string, you can automatically @@ -76,7 +76,7 @@ x-paths: Set the maximum character length recommended for this string and its translations. Not specifying or setting to 'null' implies no maxLength and on update - will remove any existing maxLegnth. + will remove any existing maxLength. type: integer format: description: >- @@ -207,7 +207,7 @@ x-paths: If an **Add strings** request takes longer than 60 seconds to process, a `202` response will be returned, indicating that the process of creating strings is continuing but not yet complete. This response will include a - `proccessUid` value which can be used to check the progress of the + `processUid` value which can be used to check the progress of the request. @@ -642,15 +642,10 @@ components: data: properties: createdDate: - description: Total number of strings captured as a result of the request. + description: Date when the create strings request was submitted. type: string modifiedDate: - description: >- - If the request takes longer than 60 seconds to process, a - `202` response will be returned, indicating the request has - not failed, but is not yet complete. Use the processUid - value to check the status of the request using the Check - Create String Status request. + description: Date when the create strings request was last modified. type: string processState: description: State of the request @@ -676,7 +671,7 @@ components: type: string type: object processUid: - description: Unique identifer for a create string request. + description: Unique identifier for a create string request. type: string type: object type: object @@ -684,15 +679,15 @@ components: description: Information on the created or updated string properties: hashcode: - description: The generated unique idenitfier for this created or updated string. + description: The generated unique identifier for this created or updated string. type: string overWritten: - description: Idenitfies if the string was already in the system. + description: Identifies whether the string already existed in the system. type: string parsedStringText: description: >- The text for this string used to define its uniqueness in the - Smartling system. This is after placeholders have been processed + Smartling system. This is after placeholders have been processed and escaping normalization has been applied. type: string stringText: @@ -703,10 +698,10 @@ components: type: string type: object StringInfo: - description: Information on string + description: Information on a string properties: hashcode: - description: The generated unique idenitfier for this created or updated string. + description: The generated unique identifier for this created or updated string. type: string keys: description: >- @@ -725,7 +720,7 @@ components: parsedStringText: description: >- The text for this string used to define its uniqueness in the - Smartling system. This is after placeholders have been processed + Smartling system. This is after placeholders have been processed and escaping normalization has been applied. type: string stringText: @@ -781,7 +776,7 @@ components: description: Information on a translation properties: hashcode: - description: The generated unique idenitfier for this created or updated string. + description: The generated unique identifier for this created or updated string. type: string keys: description: >- @@ -800,7 +795,7 @@ components: parsedStringText: description: >- The text for this string used to define its uniqueness in the - Smartling system. This is after placeholders have been processed + Smartling system. This is after placeholders have been processed and escaping normalization has been applied. type: string stringText: @@ -817,7 +812,7 @@ components: type: string pluralForm: description: >- - Pural form of the translation. `null` if this translation is + Plural form of the translation. `null` if this translation is not a plural. type: string translation: From 87ab50f4caa6e9748fdc5d046d0f9c4ee613524b Mon Sep 17 00:00:00 2001 From: Dmitry Studynsky Date: Wed, 24 Jun 2026 10:19:55 -0400 Subject: [PATCH 8/8] TCM-6557 Document preview URL behavior for branch vs PR builds Co-Authored-By: Claude Sonnet 4.6 (1M context) --- CLAUDE.md | 4 +++- README.md | 5 +++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 73021dab..f38c219f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,6 +42,8 @@ The local server URL is printed to console on startup. The swagger-editor URL is ## CI/CD -- Jenkins builds on every branch; non-master branches deploy a preview at `https://api-reference.smartling.com/preview/` +- Jenkins builds on every branch; non-master branches deploy a preview - the URL depends on whether a PR is open: + - No PR open: `https://api-reference.smartling.com/preview/` + - PR open: `https://api-reference.smartling.com/preview/pr-` (Jenkins uses the PR ref as `BRANCH_NAME`) - `master` deploys to the main documentation site - Preview branches are not auto-cleaned; stale previews must be cleaned manually via the `gh-pages` branch (see README.md) diff --git a/README.md b/README.md index 51ff3158..60101b79 100644 --- a/README.md +++ b/README.md @@ -7,8 +7,9 @@ - Look full spec: + JSON https://api-reference.smartling.com/swagger.json + YAML https://api-reference.smartling.com/swagger.yaml -- Preview spec version for branch ``: https://api-reference.smartling.com/preview/ - (Note: use lower case name in the url for the branch) +- Preview spec version: + - By branch name (before opening a PR): https://api-reference.smartling.com/preview/ + - By PR number (after opening a PR): https://api-reference.smartling.com/preview/pr- **Warning:** All above links are updated only after Jenkins finishes deployment