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 Files API
version: 2.0.0
x-logo:
url: smartling_logo.png
servers:
- url: https://api.smartling.com
tags:
- name: Files
description: 'Files are typically how you can exchange your content with Smartling to
get translations. Smartling supports a wide variety of [file
types](https://help.smartling.com/hc/en-us/articles/360007998893). When
you upload a file to Smartling, it gets parsed into strings, which will
then be sent into the translation queue.
The complete list of supported file types is available [here](https://help.smartling.com/hc/en-us/articles/360007998893). For information on file directives, please refer to the documentation for each specific file type.'
paths:
/files-api/v2/projects/{projectId}/file:
post:
summary: Upload file
description: 'This uploads original source content to Smartling.
The curl example provided will upload your Java properties file directly
into the Smartling project identified by the `projectId`. Smartling will
ingest this file, parse out the keys and text as strings for
translation. At this point, content is ready for translation.
'
operationId: uploadSourceFile
tags:
- Files
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:
format: uid
type: string
requestBody:
content:
multipart/form-data:
schema:
properties:
file:
type: string
format: binary
description: The file contents to upload.
fileUri:
type: string
description: 'A value that uniquely identifies the uploaded file. This ID
can be used to request the file back. We recommend that you
use file path and file name, similar to how version control
systems identify the file.
The maximum length is 512 characters.
Example: `/myproject/i18n/ui.properties`
'
maxLength: 512
fileType:
$ref: '#/components/schemas/FileType'
smartling.namespace:
type: string
description: 'This is only for accounts created after July 31st, 2015. Define a custom
[namespace](https://help.smartling.com/hc/en-us/articles/360008143833)
for the file.
**Note**: While this parameter shares the format of other
file directives, it will not work as an inline directive and
must be specified in the API call.
'
smartling.file_charset:
type: string
description: 'Specifies a custom charset for text-format files. The value
should be the name of the character set. See a full list of
supported character sets [here](https://help.smartling.com/hc/en-us/articles/40930524759835).
If this directive is not used, Smartling will use the
```Content-Type``` request header to determine if the
content is encoded with UTF-16, UTF-16B or UTF-16LE. If
there is no ```Content-Type``` header, Smartling will
examine the file for UTF-16 characters. If none are
detected, UTF-8 encoding will be used.
**Note**: Once this property has been set for a file, it
cannot be changed. If you reupload the file, it will use the
original charset, even if you change the directive. An error
will be returned if this directive is used when uploading
binary-format file types, such as Office or IDML files.
'
smartling.[command]:
type: string
description: 'Provides custom parser configuration for supported file
types. See [Supported File Types](https://help.smartling.com/hc/en-us/articles/360007998893)
for more details.
'
callbackUrl:
type: string
maxLength: 255
format: url
description: 'A GET request that creates a callback to a URL when all authorized strings from a file are 100%
published for a locale.* The callback gives the
fileUri and locale with the format
`http[/s]://your.url?locale=xx-XX&fileUri=your.file`. If you
upload the file again, without a callbackUrl, it will remove
any previous callbackUrl for that file. The RequestBin
(http://requestb.in) service is a convenient way to test a
callback. RequestBin generates a short-lived disposable URL
that displays all posted requests.
If a callback fails, Smartling will make multiple attempts
to reach the designated URL. However, we do not keep
retrying a failed callback indefinitely. Try to make sure
your callback URL is as stable as possible and be aware that
callbacks are not a 100% reliable way of being notified that
a file is published.
If the upload has begun but is taking more than a minute to
complete, it responds with a `202` status.
*This is the default behavior. There are cases when the callback could be triggered even when not all authorized strings are published, depending on your project configuration. Contact your Smartling Representative if you have questions about your project’s callback configuration.
'
required:
- file
- fileUri
- fileType
type: object
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FilesAPIUploadSuccessResponse'
examples:
response:
value:
response:
code: SUCCESS
data:
overWritten: true
stringCount: 10
wordCount: 2
'202':
description: ACCEPTED
content:
application/json:
schema:
$ref: '#/components/schemas/FilesAPIUploadAcceptedResponse'
examples:
response:
value:
response:
code: SUCCESS
data:
message: Your file was successfully uploaded. Word and string counts are not available right now.
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'423':
description: The requested file is currently being processed by another operation. The file will be unlocked after the operation completes.
content:
application/json:
schema:
$ref: '#/components/schemas/Error423Response'
examples:
response:
value:
response:
code: RESOURCE_LOCKED
errors:
- key: resource.locked
message: The file is currently being processed and will be available in a few minutes.
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
x-code-samples:
- lang: curl
source: 'curl -X POST -H "Authorization: Bearer $smartlingToken" -F "file=@$uploadFilePath;type=text/plain" -F "fileUri=$uploadFileSmartlingUri" -F "fileType=$uploadFileSmartlingType" "https://api.smartling.com/files-api/v2/projects/$smartlingProjectId/file"
'
get:
summary: Download source file
description: 'This downloads the original version of the requested file from
Smartling.
It is important to check the HTTP response status code. If Smartling
finds and returns the file normally, you will receive a `200` SUCCESS
response. If you receive a response status code other than `200`, the
requested file will not be part of the response.
When you upload a UTF-16 character encoded file, then /file/get requests
for that file will have a character encoding of UTF-16. All other
uploaded files will return with a character encoding of UTF-8.
You can always use the content-type header in the response of a file/get
request to determine the character encoding.
The filename is based on the fileUri associated with the requested file.
In most cases, the filename is exactly the fileUri provided. The only
exception to this is with .pot gettext files. When a .pot file is
specified as the fileUri, Smartling returns a .po file.
'
tags:
- Files
operationId: downloadSourceFile
parameters:
- name: projectId
description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: path
required: true
schema:
type: string
- name: fileUri
description: Value that uniquely identifies the downloaded file.
in: query
required: true
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
format: binary
'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 --data-urlencode "fileUri=$smartlingFileUri" "https://api.smartling.com/files-api/v2/projects/$smartlingProjectId/file"
'
/files-api/v2/projects/{projectId}/file/status:
get:
summary: Status of file for each locale
tags:
- Files
description: "Returns information on a specific file.\n\n**Example:**\n```bash\n curl -X GET -H \"Authorization: Bearer {token}\" 'https://api.smartling.com/files-api/v2/projects/{projectId}/file/status?fileUri=file.properties'\n```\n"
operationId: getFileTranslationStatusAllLocales
parameters:
- name: projectId
description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: path
required: true
schema:
type: string
- name: fileUri
description: Smartling value that uniquely identifies a file in Smartling
in: query
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FilesAPIStatusAllLocalesSuccessResponse'
examples:
response:
value:
response:
code: SUCCESS
data:
created: '2017-09-06T20:29:15Z'
directives:
file_uri_as_namespace: 'true'
fileType: csv
fileUri: /files/test_translation_import.csv
hasInstructions: false
items:
- authorizedStringCount: 0
authorizedWordCount: 0
completedStringCount: 0
completedWordCount: 0
excludedStringCount: 0
excludedWordCount: 0
localeId: ru-RU
lastUploaded: '2017-09-06T20:29:15Z'
namespace:
name: /files/test_trans_import.csv
parserVersion: 4
totalCount: 1
totalStringCount: 1
totalWordCount: 1
totalPageCount: null
pageCountStatus: NOT_AVAILABLE_UNSUPPORTED
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
/files-api/v2/projects/{projectId}/locales/{localeId}/file/status:
get:
summary: Status of file for a single locale
description: 'Returns detailed status information on a specific file.
**Example:**
```bash
curl -X GET -H "Authorization: Bearer {token}" ''https://api.smartling.com/files-api/v2/projects/{projectId}/locales/{localeId}/file/status?fileUri=file.properties''
```
'
tags:
- Files
operationId: getFileTranslationStatusSingleLocale
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: Identifier for a locale.
in: path
name: localeId
required: true
schema:
type: string
- description: Smartling value that uniquely identifies a file in Smartling
in: query
name: fileUri
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FilesAPIStatusSingleLocaleSuccessResponse'
examples:
response:
value:
response:
code: SUCCESS
data:
authorizedStringCount: 4
authorizedWordCount: 5
completedStringCount: 0
completedWordCount: 0
created: '2017-05-27T12:45:36Z'
excludedStringCount: 0
excludedWordCount: 0
fileType: javaProperties
fileUri: /files/4.properties
hasInstructions: false
lastUploaded: '2017-05-27T12:45:36Z'
parserVersion: 4
totalStringCount: 5
totalWordCount: 9
totalPageCount: null
pageCountStatus: NOT_AVAILABLE_UNSUPPORTED
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
/files-api/v2/projects/{projectId}/locales/{localeIds}/file:
get:
summary: Download translated file (single locale or multi-locale)
tags:
- Files
description: "Downloads the requested translated file from Smartling. \n\nThis endpoint supports two modes depending on the value of `localeIds`:\n\n### **Single-locale mode**\n- Provide a **single locale ID**, e.g. `fr-FR`\n- Smartling returns a file containing translations only for that locale\n- Supported for **all file types**.\n\n### **Multi-locale mode**\n- Provide a **comma-separated list of locale IDs**, e.g. `fr-FR,de-DE,es-ES`\n- Or specify `all` to include all available locales\n- Smartling returns a **combined multi-locale file** with translations for all specified locales inside one file\n- Supported only for:\n **MADCAP, DITA_ZIP, CSV, XLSX_TEMPLATE, XCSTRINGS**\n\n\n---\n\nIt is important to check the HTTP response status code. If Smartling\nfinds and returns the file normally, you will receive a `200` SUCCESS\nresponse. If you receive any other response status code other than\n`200`, the requested file will not be part of the response.\n\nWhen you upload a UTF-16 character encoded file, then /file/get requests\nfor that file will have a character encoding of UTF-16. All other\nuploaded files will be returned with a character encoding of UTF-8.\n\nYou can always use the content-type header in the response of a file/get\nrequest to determine the character encoding.\n\n**Note**: The filename in the response header is based on the fileUri\nassociated with the requested file. In most cases, the filename is\nexactly the fileUri provided. The only exception to this is with .pot\ngettext files. When a .pot file is specified as the fileUri, Smartling\nreturns a .po file.\n"
operationId: downloadTranslatedFile
parameters:
- name: projectId
description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: path
required: true
schema:
type: string
- name: localeIds
description: "One of:\n- A **single locale ID**, e.g. `fr-FR` → single-locale mode \n- A **comma-separated list** of locale IDs, e.g. `fr-FR,de-DE` → multi-locale mode \n- `all` → download translations for all available locales\n"
in: path
required: true
schema:
type: string
- name: fileUri
description: Value that uniquely identifies the downloaded file
in: query
required: true
schema:
type: string
- name: retrievalType
description: 'Determines the desired format for the download. Applies to translated files only.
| retrievalType | Description |
|---------------|-------------|
| pending | Smartling returns any translations (including non-published translations)|
| published | Smartling returns only published/pre-published translations.|
| pseudo | Smartling returns a modified version of the original text with certain characters transformed and the text expanded. For example, the uploaded string "This is a sample string", will return as "T~hís ~ís á s~ámpl~é str~íñg". Pseudo translations enable you to test how a longer string integrates into your application.|
| contextMatchingInstrumented | Smartling returns a modified version of the original file with strings wrapped in a specific set of Unicode symbols that can later be recognized and matched by the Chrome Context Capture Extension.|
'
in: query
required: false
schema:
enum:
- pending
- published
- pseudo
- contextMatchingInstrumented
type: string
- name: includeOriginalStrings
description: 'Specifies whether Smartling will return the original string or an
empty string where no translation is available. This parameter is
only supported for ANDROID, ARB, GETTEXT, IDML, IOS, JAVA Properties, JSON, QT, STRINGSDICT,
XLIFF, XML, and YAML files. If unset, the default is <code>true</code>.
| Value | Description |
|-------|-------------|
| true | If there is no translation, Smartling returns the original string. |
| false | If there is no translation, Smartling returns an empty string. |
'
in: query
required: false
schema:
type: boolean
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
format: binary
'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" -o $smartlingLocaleId$smartlingFileUri -G --data-urlencode "fileUri=$smartlingFileUri" "https://api.smartling.com/files-api/v2/projects/$smartlingProjectId/locales/$smartlingLocaleId/file"
'
/files-api/v2/projects/{projectId}/locales/all/file/zip:
get:
summary: Download all translations of file
description: 'Download a ZIP archive with all translations for the requested file.
Unlike the "Download translated file" endpoint, you get a ZIP archive
with all translations of a specific file.
It is important to check the HTTP response status code. If Smartling
finds and returns the file normally, you will receive a `200` SUCCESS
response. If you receive any other response status code than `200`, the
requested files will not be part of the response.
When you upload a UTF-16 character encoded file, then /file/get requests
for that file will have a character encoding of UTF-16. All other
uploaded files will be returned with a character encoding of UTF-8.
You can always use the content-type header in the response of a file/get
request to determine the character encoding.
'
tags:
- Files
operationId: downloadTranslatedFilesAllLocales
parameters:
- name: projectId
description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: path
required: true
schema:
type: string
- name: fileUri
description: Smartling value that uniquely identifies a file in Smartling
in: query
required: true
schema:
type: string
- name: retrievalType
description: 'Determines the desired format for the download. Applies to translated files only.
| retrievalType | Description |
|---------------|-------------|
| pending | Smartling returns any translations (including non-published translations).|
| published | Smartling returns only published/pre-published translations.|
| pseudo | Smartling returns a modified version of the original text with certain characters transformed, and the text expanded. For example, the uploaded string "This is a sample string", will return as "T~hís ~ís á s~ámpl~é str~íñg". Pseudo translations enable you to test how a longer string integrates into your application.|
| contextMatchingInstrumented | Smartling returns a modified version of the original file with strings wrapped in a specific set of Unicode symbols that can later be recognized and matched by the Chrome Context Capture Extension.|
'
in: query
required: false
schema:
enum:
- pending
- published
- pseudo
- contextMatchingInstrumented
type: string
- name: includeOriginalStrings
description: 'Specifies whether Smartling will return the original string or an
empty string where no translation is available. This parameter is
only supported for ANDROID, ARB, GETTEXT, IDML, IOS, JAVA Properties, JSON, QT, STRINGSDICT,
XLIFF, XML, and YAML files. If unset, the default is <code>true</code>.
| Value | Description |
|-------|-------------|
| true | If there is no translation, Smartling returns the original string. |
| false | If there is no translation, Smartling returns an empty string. |
'
in: query
required: false
schema:
type: boolean
- name: zipFileName
description: Name for the downloaded zip file. If unset, the default is ```translations.zip```
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
format: binary
'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 GET -H "Authorization: Bearer $smartlingToken" ''https://api.smartling.com/files-api/v2/projects/{projectId}/locales/all/file/zip?fileUri=yourfile.json&retrievalType=published''
'
/files-api/v2/projects/{projectId}/files/zip:
get:
summary: Download multiple translated files (DEPRECATED)
description: "Download ZIP archive with the requested translated files.\n\nUnlike \"Download all translations of the file\" you can specify multiple\nfile URIs (limit is 300 files) and locale IDs to select which files and languages you want to download.\n\nIt is important to check the HTTP response status code. If Smartling\nfinds and returns the file normally, you will receive a `200` SUCCESS\nresponse. If you receive any other response status code than `200`, the\nrequested files will not be part of the response.\n\nWhen you upload a UTF-16 character encoded file, then /file/get requests\nfor that file will have a character encoding of UTF-16. All other\nuploaded files will return with a character encoding of UTF-8.\n\nYou can always use the content-type header in the response of a file/get\nrequest to determine the character encoding.\n\n**Example:**\n\n```bash\n curl -X GET -H \"Authorization: Bearer {token}\" 'https://api.smartling.com/files-api/v2/projects/{projectId}/files/zip?localeIds[]=de-DE&fileUris[]=yourfile.json'\n```\n"
tags:
- Files
operationId: downloadMultipleTranslatedFiles
parameters:
- name: projectId
description: A unique project identifier. This can be found in the Smartling Dashboard under Account Settings > API.
in: path
required: true
schema:
type: string
- name: fileUris[]
description: Smartling values that each uniquely identify a file. The limit is 300 files.
explode: true
in: query
required: true
schema:
items:
type: string
type: array
- name: localeIds[]
description: List of locales to download.
explode: true
in: query
required: true
schema:
items:
type: string
type: array
- name: retrievalType
description: 'Determines the desired format for the download. Applies only to
translated files.
| retrievalType | Description |
|---------------|-------------|
| pending | Smartling returns any translations (including non-published translations)|
| published | Smartling returns only published/pre-published translations.|
| pseudo | Smartling returns a modified version of the original text with certain characters transformed and the text expanded. For example, the uploaded string "This is a sample string", will return as "T~hís ~ís á s~ámpl~é str~íñg". Pseudo translations enable you to test how a longer string integrates into your application.|
| contextMatchingInstrumented | Smartling returns a modified version of the original file with strings wrapped in a specific set of Unicode symbols that can later be recognized and matched by the Chrome Context Capture Extension.|
'
in: query
required: false
schema:
enum:
- pending
- published
- pseudo
- contextMatchingInstrumented
type: string
- name: includeOriginalStrings
description: 'Specifies whether Smartling will return the original string or an
empty string where no translation is available. This parameter is
only supported for ANDROID, ARB, GETTEXT, IDML, IOS, JAVA Properties, JSON, QT, STRINGSDICT,
XLIFF, XML, and YAML files. If unset, the default is <code>true</code>.
| Value | Description |
|-------|-------------|
| true | If there is no translation, Smartling returns the original string. |
| false | If there is no translation, Smartling returns an empty string. |
'
in: query
required: false
schema:
type: boolean
- name: fileNameMode
description: 'Determines how files in the ZIP file will be named. If not set, the
full original file path will be used as the filename.
| fileNameMode | Description |
|--------------|-------------|
| UNCHANGED | Full original file path is used |
| TRIM_LEADING | Remove all except the last path segment. e.g. ```/en/strings/nav.properties``` becomes ```nav.properties```|
| LOCALE_LAST | Adds a locale folder to the file path directly before the filename. e.g. ```/strings/nav.properties``` becomes ```/strings/en/nav.properties``` |
'
in: query
required: false
schema:
enum:
- UNCHANGED
- TRIM_LEADING
- LOCALE_LAST
type: string
- name: localeMode
description: 'Determines how locales will be handled in the downloaded zip
| localeMode | Description |
|------------|-------------|
| LOCALE_IN_PATH | Locale code is added to the end of the file path. e.g. ```/strings/es-ES/nav.properties```. |
| LOCALE_IN_NAME | Locale code is added to the end of the file name e.g. ```/strings/nav_es-ES.properties```. |
| LOCALE_IN_NAME_AND_PATH | Locale code is added to both the path and the filename. e.g. ```/strings/es-ES/nav_es-ES.properties```. |
'
in: query
required: false
schema:
enum:
- LOCALE_IN_PATH
- LOCALE_IN_NAME
- LOCALE_IN_NAME_AND_PATH
type: string
- name: zipFileName
description: Name for the downloaded ZIP file. If unset, default is ```translations.zip```
in: query
required: false
schema:
type: string
responses:
'200':
description: OK
content:
'*/*':
schema:
type: string
format: binary
'400':
$ref: '#/components/responses/Error400ResponseDefinition'
'401':
$ref: '#/components/responses/Error401ResponseDefinition'
'429':
$ref: '#/components/responses/Error429ResponseDefinition'
'500':
$ref: '#/components/responses/Error500ResponseDefinition'
post:
summary: Download multiple translated files
description: "Download ZIP arc
# --- truncated at 32 KB (87 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/smartling/refs/heads/main/openapi/smartling-files-api-openapi.yml