openapi: 3.0.0
info:
contact:
email: support@smartling.com
description: 'Before you begin using the Smartling APIs, we recommend going through our [Developer documentation](https://help.smartling.com/hc/en-us/categories/1260801686149).
'
termsOfService: https://www.smartling.com/legal
title: Smartling REST API Reference Account & Projects Strings API
version: 2.0.0
x-logo:
url: smartling_logo.png
servers:
- url: https://api.smartling.com
tags:
- name: Strings
description: 'A string is a piece of translation. Based on the source content, strings
can be parsed differently. A string is then broken down further, into one
or more segments.
The Strings API allows you to directly upload strings to a Smartling
project and fetch original strings or translations.
For each string in a Smartling project, there is a unique identifier
created by hashing together the parsed string text, [variant
metadata](https://help.smartling.com/hc/en-us/articles/360008143853), and
in some cases,
[namespace](https://help.smartling.com/hc/en-us/articles/360008143833).
When adding strings via the Strings API, each string will be unique. If
you try to create a string with identical variant metadata and string text
to a string that already exists in the project, the string will be
overwritten.'
paths:
/strings-api/v2/projects/{projectId}:
post:
summary: Add strings
description: 'Uploads an array of strings to a Smartling project. A maximum of 100 strings can be created per request. A request with more than 100 items 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 the same hashcode, the existng 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 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 will be returned, including a `processUid` value that can be used to check on the progress of the request.
If you set up a POST callback for the string, you can automatically receive the translation for a string as soon as it is complete. See [Callbacks](https://help.smartling.com/hc/en-us/articles/1260805504109) for more details.'
tags:
- Strings
operationId: addStringsToProject
parameters:
- in: path
name: projectId
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
properties:
strings (Required):
items:
properties:
stringText:
description: The text of the string you want to create. This is the only required value for a string object.
type: string
variant:
description: Creates variant metadata for a new string.
type: string
callbackUrl:
description: If provided a callback request will be sent to this URL when translation for the string is complete. See our callbacks documentation for more details.
type: string
callbackMethod:
description: With a given callbackUrl, this defines the http method to use. See our callbacks documentation for more details.
type: string
instruction:
description: Creates an instruction that is displayed to translators in the Smartling Translation Interface.
type: string
maxLength:
description: 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.
type: number
format:
description: 'Sets whether or not the string should be parsed as HTML. Accepted values are ''html'', ''plain_text'' and ''auto''. If set to auto, Smartling will attempt to detect the presence of HTML tags in the string.
"When strings are parsed as HTML, Smartling will automatically ampersand-escape special characters such as angle brackets (<) and quotes ("). For example, if you upload the string _Dave says "hello"_. and set format to HTML, Smartling will return the string with ampersand-escaping: _Dave says &quot;hello&quot;_."'
type: string
required:
- stringText
type: object
minItems: 1
type: array
placeholderFormat:
description: Specifies a standard placeholder format. Accepted values are none, c, ios, python, java, yaml, qt, resx. See [Placeholders in Resource Files](https://help.smartling.com/hc/en-us/articles/360008143433) for more detail.
type: string
placeholderFormatCustom:
description: Specifies a custom placeholder with a Java Regular Expression. For example \\[.+?\\] would capture all values surrounded by square brackets as placeholders. See [Placeholders in Resource Files](https://help.smartling.com/hc/en-us/articles/360008143433) for more detail.
type: string
namespace:
description: Used to generate the unique hashcode for all strings in the request. If you want to have two versions of a string with the same text and variant metadata, you can keep them unique by assigning a different namespace to each string. If not provided, default value is _smartling.strings-api.default.namespace_. A _NULL_ value is permitted.
type: string
type: object
required:
- strings
responses:
'200':
content:
application/json:
examples:
response:
value:
response:
code: SUCCESS
data:
items:
- hashcode: bd603147d945h3ec74d6874422ebe4e0
overWritten: 'true'
parsedStringText: 'Search results for {0}:'
stringText: 'Search results for [city]:'
variant: variant value
processUid: d6414f8c-4gdf-4415-9a69-f8e7902ca9ec
stringCount: 1
wordCount: 4
schema:
$ref: '#/components/schemas/CreateStringResponse'
description: OK
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateStringResponse'
description: ACCEPTED
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: 'curl -X POST -H "Authorization: Bearer $smartlingToken" -H "Content-Type: application/json" -d "$smartlingStringJSON" https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId
'
/strings-api/v2/projects/{projectId}/processes/{processUid}:
get:
summary: Check string status
description: "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 request.\n\nThis request can return:\n * `\"processState\": \"OPEN\"` which indicates that the request is still continuing.\n * `\"processState\": \"CLOSED\"` indicates the request has successfully completed.\n * `\"processState\": \"FAILED\"` means the request could not be completed.\n\nProcesses have a limited lifespan after they are complete. This request will fail if you specify an expired `processUid`."
tags:
- Strings
operationId: getAddStringsToProjectRequestStatus
parameters:
- in: path
name: projectId
required: true
schema:
format: uuid
type: string
- in: path
name: processUid
required: true
schema:
format: uuid
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateStringStatusResponse'
description: OK
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: 'curl -H "Authorization: Bearer $smartlingToken" -G https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId/processes/$processUid
'
/strings-api/v2/projects/{projectId}/source-strings:
get:
summary: List all source strings
description: 'Returns source strings from Smartling. You can get strings by specifying a file you want strings for, or you can specify individual strings by hashcode.
_If you do not specify at least one of these parameters (`hashcodes` or `fileUri`) no results will be returned._
**Note**: If you use this call to get strings that are not added via the Strings API, you may see differences in the response.
You may see a value for `parsedStringText` but a `null` value for `stringText`. The `stringText` records the raw input received by the Strings API, and therefore will only appear for strings uploaded via the Strings API.
If you are getting a GDN string, the original placeholder values you used will not be returned as these are not saved by Smartling. GDN strings will have placeholders in the format `{0}`, `{1}`, etc.'
tags:
- Strings
operationId: getAllSourceStringsByProject
parameters:
- in: path
name: projectId
required: true
schema:
format: uuid
type: string
- description: Hashcodes for each string you want to get source strings for.
in: query
name: hashcodes
schema:
items:
type: string
type: array
- description: URI of a file you want to get strings for.
in: query
name: fileUri
schema:
type: string
- description: By default, responses will be limited to 500 per request. This is also the maximum allowed value.
in: query
name: limit
schema:
type: number
- description: Pagination setting. Default is 0.
in: query
name: offset
schema:
type: number
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StringResponse'
description: OK
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: 'curl -H "Authorization: Bearer $smartlingToken" -G -d "fileUri=$smartlingFileUri" https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId/source-strings
'
post:
summary: List all source strings (POST)
description: 'Returns source strings from Smartling. You can get strings by specifying a file you want strings for, or you can specify individual strings by hashcode.
_If you do not specify at least one of these parameters (`hashcodes` or `fileUri`) no results will be returned._
**Note**: If you use this call to get strings that are not added via the Strings API, you may see differences in the response.
You may see a value for `parsedStringText` but a `null` value for `stringText`. The `stringText` records the raw input received by the Strings API, and therefore will only appear for strings uploaded via the Strings API.
If you are getting a GDN string, the original placeholder values you used will not be returned as these are not saved by Smartling. GDN strings will have placeholders in the format `{0}`, `{1}`, etc.'
tags:
- Strings
operationId: getAllSourceStringsByProjectPost
parameters:
- in: path
name: projectId
required: true
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
hashcodes:
description: Hashcodes for each string you want to get source strings for.
type: array
items:
type: string
fileUri:
description: URI of a file you want to get strings for.
type: string
limit:
description: By default, responses will be limited to 500 per request. This is also the maximum allowed value.
type: number
offset:
description: Pagination setting. Default is 0.
type: number
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StringResponse'
description: OK
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: 'curl -H "Authorization: Bearer $smartlingToken" -H "Content-Type: application/json" -d ''{"fileUri": "$smartlingFileUri"}'' https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId/source-strings
'
/strings-api/v2/projects/{projectId}/translations:
get:
summary: List all translations
description: 'Returns translated strings from Smartling. You can get translations by specifying a file you want strings for, or you can specify individual strings by hashcode.
_If you do not specify at least one of these parameters (`hashcodes` or `fileUri`) no results will be returned._
**Note**: If you use this call to get strings that were not created via the Strings API, you may see differences in the response.
Only authorized and active strings will be returned. Excluded, unauthorized, and inactive strings will not be returned.
You may see a value for `parsedStringText` but a `null` value for `stringText`. The `stringText` records the raw input received by the Strings API, and therefore will only appear for strings uploaded via the Strings API.
If you are getting a GDN string, the original placeholder values you used will not be returned as these are not saved by Smartling. GDN strings will have placeholders in the format `{0}`, `{1}`, etc.'
tags:
- 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
- description: Hashcodes for each string you want to get translations for.
in: query
name: hashcodes
schema:
items:
type: string
type: array
- description: Smartling ID for the language you want to get translations for.
in: query
name: targetLocaleId
required: true
schema:
type: string
- description: Sets the types of translations you want returned. `published` will only return translations that have completed their workflows and been published. `pending` will return any saved translations.
in: query
name: retrievalType
schema:
enum:
- pending
- published
type: string
- description: URI of a file you want to get translations for.
in: query
name: fileUri
schema:
type: string
- description: Pagination setting. By default, responses will be limited to 500 per request. This is also the maximum allowed value.
in: query
name: limit
schema:
type: number
- description: Pagination setting. Default is 0.
in: query
name: offset
schema:
type: number
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationResponse'
description: OK
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: 'curl -H "Authorization: Bearer $smartlingToken" -G https://api.smartling.com/strings-api/v2/projects/$smartlingProjectId/translations
'
post:
summary: List all translations (POST)
description: 'Returns translated strings from Smartling. You can get translations by specifying a file you want strings for, or you can specify individual strings by hashcode.
_If you do not specify at least one of these parameters (`hashcodes` or `fileUri`) no results will be returned._
**Note**: If you use this call to get strings that were not created via the Strings API, you may see differences in the response.
Only authorized and active strings will be returned. Excluded, unauthorized, and inactive strings will not be returned.
You may see a value for `parsedStringText` but a `null` value for `stringText`. The `stringText` records the raw input received by the Strings API, and therefore will only appear for strings uploaded via the Strings API.
If you are getting a GDN string, the original placeholder values you used will not be returned as these are not saved by Smartling. GDN strings will have placeholders in the format `{0}`, `{1}`, etc.'
tags:
- 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
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- targetLocaleId
properties:
hashcodes:
description: Hashcodes for each string you want to get translations for.
type: array
items:
type: string
targetLocaleId:
description: Smartling ID for the language you want to get translations for.
type: string
retrievalType:
description: Sets the types of translations you want returned. `published` will only return translations that have completed their workflows and been published. `pending` will return any saved translations.
type: string
enum:
- pending
- published
fileUri:
description: URI of a file you want to get translations for.
type: string
limit:
description: Pagination setting. By default, responses will be limited to 500 per request. This is also the maximum allowed value.
type: number
offset:
description: Pagination setting. Default is 0.
type: number
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TranslationResponse'
description: OK
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: '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:
schemas:
Error500Response:
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- GENERAL_ERROR
- MAINTENANCE_MODE_ERROR
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
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
Error400Response:
type: object
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- VALIDATION_ERROR
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
SuccessResponse:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- SUCCESS
type: string
required:
- code
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
Error429Response:
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- MAX_OPERATIONS_LIMIT_EXCEEDED
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
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
Error401Response:
properties:
response:
properties:
code:
description: Indicates whether the response was successful or what error has occured.
enum:
- AUTHENTICATION_ERROR
- AUTHORIZATION_ERROR
type: string
errors:
items:
$ref: '#/components/schemas/Error'
type: array
required:
- code
- errors
type: object
required:
- response
type: object
Error:
type: object
properties:
key:
example: general_error
type: string
message:
example: Unexpected server error
type: string
details:
example: {}
type: object
required:
- key
- message
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
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
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
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
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smartling/refs/heads/main/openapi/smartling-strings-api-openapi.yml