Applanga REST API

Applanga REST API (1.0)

Introduction

The Applanga Rest API allows you to access the platform to request or send translation data as JSON, edit your content on Applanga (e.g. changing, adding, deleting, etc) and to control certain features of the platform (e.g. adding tags, uploading screenshots, etc) via API calls.

Applanga API is organized around REST, accepts and returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

To make requests to the Applanga API you first need to create a Project in the Applanga Dashboard.

Then you need to get an API Token from the Project Settings (click Project Settings in the Project overview), and click Show API Token.

POST Requests may also require a Personal Access Token to be able to trace actions to a specific user. The Personal Access Token can be sent on any POST request but it is mandatory for some.

Authorization

1. API Token

To authenticate your request you need to set the Authorization header to carry your API Token in the bearer format (as described here https://tools.ietf.org/html/rfc6750#page-5 ). The value of the Authorization header needs to be 'Bearer {apiToken}'. Example: Authorization: Bearer xxxxxxxxxxxxxxxxxxxx!xxxxxxxxxxxxxxxxxxxxxx.

2. Personal Access Token

For POST, PUT, and DELETE project related requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token. Example: X-Personal-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxx.

For non project related requests the Personal Access Token must be placed in Authorization header. Example: Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxx.

3. Project Identifier

You also need to pass the id of your app to the query with the app parameter. https://api.applanga.com/v1/api?app={app_id}. The app_id is the first part of your API token until the ! e.g. if your API Token would be 54e49f570de187711f9a5936!64d6e85c0111f758748898e3181a25b7 the app_id is 54e49f570de187711f9a5936.

4. Branching Projects

If you are using a project with Branching and want to target a specific branch you also need to provide the branch_id through the branch parameter. You can get the branch_id either in the Settings of your application or request it via an api route (see Request Branch Info). Example: https://api.applanga.com/v1/api?app={app_id}&branch={branch_id}

5. Authorized IP's

For API write access, as an additional security measure you have to specify a list of authorized IP's or IP ranges. Go to your Project in the Applanga Dashboard, click Project Settings, if you have API access you will have an input field below Show API Token which will allow you to enter IP addresses (ipv4 and ipv6) or address ranges in CIDR Notation (https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). To allow write access from all ipv4 addresses add 0.0.0.0/0, for all ipv6 addresses ::/0. For unrestricted access add both. Not adding any IP addresses/ranges will block all write access.

Payload Compression

Optional payload compression for API requests is by default supported.

To receive a response with a compressed payload you only need to set the Accept-Encoding header to gzip on a request.

The client then receives the response with a content-encoding: gzip response header and GZIP-encoded payload.

Entries

Operations associated with translations. Please note that the terms Entry and Translation are synonymous and are used interchangeably or sometimes together.

EntryStatus

additional property
object

Dataset mapped to a language name. ISO language codes corresponding to languages in the project is mapped to various entries statistics described here. Essentially the counts are calculated per language.

{
  • "<language>1": {
    },
  • "<language>2": {
    }
}

Posting translation data.

Permission Requirements(Personal access tokens):

  • create_and_update_translations

Use this endpoint to upload translation strings to a project or to a specific branch if the project is a branching project. The API will identify your project and authenticate the token. If your request is authorized the data will be written to your app and a json object describing the changes will be returned. Otherwise you will receive an http error.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
object
object

Set a custom name for any language in the request body. A language code should be set as the key and the custom language name as the value. The language set here must correspond to one of the languages in the request data or else it will be ignored.

Note that the language code must be a valid ISO language code. Applanga supports all ISO 639-1, 639-2, and 639-3 language codes. For more informations where to find them please see: Adding and Removing Languages.

Addtionally you can also specify a custom language code either as 2 letter lowercase language e.g. "pt" or combined with an uppercase region code e.g. "pt-BR". If the language code is not valid as described above an error response will be returned. As an example if you want to upload some strings for a language xx-ZZ as shown below

{
    "data": {
        "xx-ZZ" {
            "main": {
                "entries": {
                    "key1":{
                        "d":"draft1",
                        "v":"value1",
                        "src":"/src/File1"
                    },
                }
            }
        }
    }
}

to set the language display of name of xx-ZZ to Custom display name for xx-ZZ for example, update the request body like so

{
    "data": {
        "xx-ZZ" {
            "main": {
                "entries": {
                    "key1":{
                        "d":"draft1",
                        "v":"value1",
                        "src":"/src/File1"
                    },
                }
            }
        }
    },
    "languageDisplayNames": {
        "xx-ZZ": "Custom display name for xx-ZZ"
    }
}
required
object

Top-level data object

Responses

Response Schema: application/json
total
integer

Total number of entries uploaded

added
integer

Number of new entries added

updated
integer

Number of existing entries updated

tagUpdates
integer

Number of tags updated

groupChanged
integer

Count of entries reassigned to a different group

groupCountChanges
object

Maps group ids to the count of entries added

object
keys
Array of strings

Request samples

Content type
application/json
Example

Basic example with no only the setStatus set to needs review(2) in options and the value, draft set in entry data.

{
  • "options": {
    },
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "total": 1,
  • "added": 1,
  • "updated": 1,
  • "tagUpdates": 0,
  • "groupChanged": 1,
  • "groupCountChanges": {
    },
  • "_additionalData": {
    },
  • "keys": [
    ]
}

Requesting translation data.

The API will identify your project and authenticate the token and return your Project's translation data.

Note If you are using a Branching Project and want to request a specific branch you also need to provide the branch_id as a parameter, please see here The API is using a Content Delivery Network for fast and reliable content distribution. It is updated in fixed intervals and it therefore might take up to 10 minutes until changes made in the dashboard appear live in the api.

To limit the response data to certain groups, and/or languages, and/or tags, and/or status you can add query parameters requestedLanguages, requestedGroups, requestedTagIds and requestedStatus, as json string arrays which have to be urlencoded as well.

An Example for requested group main and languages en and de: https://api.applanga.com/v1/api?app=<app_id>&requestedGroups=[%22main%22]&requestedLanguages=[%22en%22,%22de%22]&requestedTagIds=[%22tag_id_1%22, %22tag_id_2%22]&requestedStatus=[1,%202].

If you do not request any languages or groups, all groups and languages will be returned. If you have not activated groups and created additional groups, all your translations will be in group main.

It is also possible to include additional data or remove data from the response by adding additional query parameters, see the query parameters below.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

includeSrc
boolean
Default: false
Example: includeSrc=true

If set to true, adds src property which describes a file origin for the specific string in that specific language. These file sources can originate from imported .xliff files or from data writte through this API.

includeStatus
boolean
Default: false
Example: includeStatus=true

If set to true, adds status property which describes the current state of the translation. Use the option in combination with keepEmptyDataEntries to include the status for entries without translation.

includeComment
boolean
Default: false
Example: includeComment=true

If set to true, adds comment property of the translation if a comment was made.

includeLockInfo
boolean
Default: false
Example: includeLockInfo=true

If set to true, adds locked property to the translation, to indicate if it is locked or not. Use the option in combination with keepEmptyDataEntries to include the locking information for entries without translation.

includeDescription
boolean
Default: false
Example: includeDescription=true

If set to true, adds description property of the translation keys in the base language.

includeMeta
boolean
Default: false
Example: includeMeta=true

If set to true, adds meta (metadata) property of the translation keys in the base language. Empty metadata values are not included.

includeMetaForAllLanguages
boolean
Default: false
Example: includeMetaForAllLanguages=true

If set to true, adds meta (metadata) property of the translation keys in all languages. Empty metadata values are not included.

includeDraft
boolean
Default: true
Example: includeDraft=false

If set to true, adds d(draft) property.

includeValue
boolean
Default: true
Example: includeValue=false

If set to true, adds v(value) property.

keepEmptyDataEntries
boolean
Default: false
Example: keepEmptyDataEntries=true

By default all groups and entries that do not have values or draft get deleted from response. Set this to true to include them.

includeUpdateDate
boolean
Default: false
Example: includeUpdateDate=true

If set to true, adds updatedAt property.

includeUserId
boolean
Default: false
Example: includeUserId=true

If set to true, adds userId property.

includeLanguageId
boolean
Default: false
Example: includeLanguageId=true

If set to true, adds languageId property under each group.

includeGroupId
boolean
Default: false
Example: includeGroupId=true

If set to true, adds groupId property under each group.

removeCrChar
boolean
Default: false
Example: removeCrChar=true

If set to true, removes Windows CR character from downloaded data.

includeStatusDescription
boolean
Default: false
Example: includeStatusDescription=true

When this parameter is set to true, the response body includes a property statusDescription, which is an object that maps translation status description to status value. An example of what this could look like is as follows

 "statusDescription": {
     "nostatus/new": 0,
     "accepted": 1,
     "needs review": 2,
     "needs translation": 3,
     "rejected": 4,
     "in order": 5,
     "testing": 1001,
     ...
 }

In the preceding example all the known translation status are present including a custom string status testing.

Example to include additionally src, status and status description: https://api.applanga.com/v1/api?app={app_id}?includeSrc=true&includeStatus=true&includeStatusDescription=true.

requestedGroups
Array of strings
Example: requestedGroups=["main"]

Limit scope of entries returned to the specified groups. Note that the group names are expected here.

requestedLanguages
Array of strings
Example: requestedLanguages=["en","de"]

Limit scope of entries returned to the specified languages. Note that the language codes are expected here.

requestedTagIds
Array of strings
Example: requestedTagIds=["669a94819a3e29a04018320e","669a94819a3e29a040183204"]

Limit scope of entries returned to the specified Tags. Note that the tag id's are expected here. If both the requestedOrderId and requestedTagIds parameters are used in the same call, the response will include only the keys that are part of the specified order and are simultaneously associated with the given tags.

requestedOrderId
string
Example: requestedOrderId=608fbe4db764186e651f8e2b

Limit scope of entries returned to the specified Order. Note an order id is needed. If both the requestedOrderId and requestedTagIds parameters are used in the same call, the response will include only the keys that are part of the specified order and are simultaneously associated with the given tags.

requestedStatus
Array of integers
Example: requestedStatus=[1, 2]

Limit scope of entries returned to the specified statuses.

Responses

Response Schema: application/json
_id
string

Project id

__v
string

Project version

draftModeEnabled
boolean
Default: false

Indicates if draft mode is enabled for the project, see this guide for more info on draft mode /docs/applanga-mobile-sdks/draft_on-device-testing.

collectMissingEnabled
boolean
Default: false
baseLanguage
string

This is also referred to as the source language of a project. Entries are translated from this language to other lnaguages.

name
string

This is the name of the project.

object

Top-level data object.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b&includeSrc=true&includeStatus=true&includeComment=true&includeLockInfo=true&includeDescription=true&includeMeta=true&includeMetaForAllLanguages=true&includeDraft=false&includeValue=false&keepEmptyDataEntries=true&includeUpdateDate=true&includeUserId=true&includeLanguageId=true&includeGroupId=true&removeCrChar=true&includeStatusDescription=true&requestedGroups=SOME_ARRAY_VALUE&requestedLanguages=SOME_ARRAY_VALUE&requestedTagIds=SOME_ARRAY_VALUE&requestedOrderId=608fbe4db764186e651f8e2b&requestedStatus=SOME_ARRAY_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "_id": "608fbe4db764186e651f8e2b",
  • "__v": "1.0",
  • "draftModeEnabled": true,
  • "collectMissingEnabled": false,
  • "baseLanguage": "en",
  • "name": "yourAppName",
  • "data": {
    }
}

Requesting project entry counts.

The API will identify your project and authenticate the token and return your App translation data.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

tagId
string
Example: tagId=608fbe4db764186e651f8e2b

This is the id of a tag, inside the given project, to filter a query by. The query will always be limited to the given Tag scope

Responses

Response Schema: application/json
additional property
object

Dataset mapped to a language name. ISO language codes corresponding to languages in the project is mapped to various entries statistics described here. Essentially the counts are calculated per language.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/entryCount?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b&tagId=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "de": {
    },
  • "en": {
    }
}

Delete one or multiple translations

Permission Requirements(Personal access tokens):

  • delete_translations

Use this endpoint to delete entries in a project. The entries are deleted in all languages.

If any of the keys provided is locked, the endpoint would return an error, showing the locked key and languages.

The API will identify your project and authenticate the token and delete the entries.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
entries
required
Array of strings

Array of entry keys to be deleted

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "entries": [
    ]
}

Response samples

Content type
application/json
{ }

Tags

Operations related to tags. Please see the following guide for more information about tags.

Creating a new tag.

Permission Requirements(Personal access tokens):

  • create_and_update_tags

Create a new tag in a project using this endpoint. The API will identify your project and authenticate the token and create a new tag.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
name
required
string

Name of the tag.

entryKeys
Array of strings

List of keys for entries assigned to the tag.

category
string

Tags can have specific category associations. Categories are used for more specific tracking of keys. Categories exist within a project and can be used to easily differentiate between tags and to track things like platforms, releases, and workflows (e.g. design review, development review, etc.) The Applanga dashboard is pre-populated with some platform-related categories: iOS, Android, Web, and Jira. Category options can be managed on the Project Settings page.

Responses

Response Schema: application/json
name
required
string

Name of the tag.

entryKeys
Array of strings

List of keys for entries assigned to the tag.

category
string

Tags can have specific category associations. Categories are used for more specific tracking of keys. Categories exist within a project and can be used to easily differentiate between tags and to track things like platforms, releases, and workflows (e.g. design review, development review, etc.) The Applanga dashboard is pre-populated with some platform-related categories: iOS, Android, Web, and Jira. Category options can be managed on the Project Settings page.

id
string

Unique identifier of the object

createdAt
string

Timestamp of when the tag was created.

updatedAt
string

Timestamp of when the tag was last updated.

Request samples

Content type
application/json
{
  • "name": "my_tag_2",
  • "entryKeys": [
    ],
  • "category": "Web"
}

Response samples

Content type
application/json
{
  • "id": "5e2996645a463ed6feabdebc",
  • "name": "my_tag_2",
  • "entryKeys": [
    ],
  • "category": "Web",
  • "createdAt": "2020-01-23T12:49:40.376Z",
  • "updatedAt": "2020-01-23T17:22:05.276Z"
}

Requesting a list of tags.

Request tags in a project with this endpoint. The API will identify your project and authenticate the token and return all the tags in the Project.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
Array
name
required
string

Name of the tag.

entryKeys
Array of strings

List of keys for entries assigned to the tag.

category
string

Tags can have specific category associations. Categories are used for more specific tracking of keys. Categories exist within a project and can be used to easily differentiate between tags and to track things like platforms, releases, and workflows (e.g. design review, development review, etc.) The Applanga dashboard is pre-populated with some platform-related categories: iOS, Android, Web, and Jira. Category options can be managed on the Project Settings page.

id
string

Unique identifier of the object

createdAt
string

Timestamp of when the tag was created.

updatedAt
string

Timestamp of when the tag was last updated.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/tags?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
[
  • {
    }
]

Requesting a tag by id.

Request for a single tag in a project with this endpoint. The API will identify your project and authenticate the token and then return the tag whose id is specified in the url denoted by tagId.

Authorizations:
apiAccessToken
path Parameters
tagId
required
string
Example: 5fd77160c876c25340b17404

Unique identifier of a tag

query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
name
required
string

Name of the tag.

entryKeys
Array of strings

List of keys for entries assigned to the tag.

category
string

Tags can have specific category associations. Categories are used for more specific tracking of keys. Categories exist within a project and can be used to easily differentiate between tags and to track things like platforms, releases, and workflows (e.g. design review, development review, etc.) The Applanga dashboard is pre-populated with some platform-related categories: iOS, Android, Web, and Jira. Category options can be managed on the Project Settings page.

id
string

Unique identifier of the object

createdAt
string

Timestamp of when the tag was created.

updatedAt
string

Timestamp of when the tag was last updated.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/tags/%7BtagId%7D?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "id": "5e2996645a463ed6feabdebc",
  • "name": "my_tag_2",
  • "entryKeys": [
    ],
  • "category": "Web",
  • "createdAt": "2020-01-23T12:49:40.376Z",
  • "updatedAt": "2020-01-23T17:22:05.276Z"
}

Updating a tag by id.

Update a tag in a project with this endpoint. The API will identify your project and authenticate the token and then the API will update the tag whose id is specified in the url with the request body.

Authorizations:
apiAccessToken
path Parameters
tagId
required
string
Example: 5fd77160c876c25340b17404

Unique identifier of a tag

query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
name
string

Name of the tag.

entryKeys
Array of strings

List of keys for entries assigned to the tag.

category
string

Tags can have specific category associations. Categories are used for more specific tracking of keys. Categories exist within a project and can be used to easily differentiate between tags and to track things like platforms, releases, and workflows (e.g. design review, development review, etc.) The Applanga dashboard is pre-populated with some platform-related categories: iOS, Android, Web, and Jira. Category options can be managed on the Project Settings page.

Responses

Response Schema: application/json
name
required
string

Name of the tag.

entryKeys
Array of strings

List of keys for entries assigned to the tag.

category
string

Tags can have specific category associations. Categories are used for more specific tracking of keys. Categories exist within a project and can be used to easily differentiate between tags and to track things like platforms, releases, and workflows (e.g. design review, development review, etc.) The Applanga dashboard is pre-populated with some platform-related categories: iOS, Android, Web, and Jira. Category options can be managed on the Project Settings page.

id
string

Unique identifier of the object

createdAt
string

Timestamp of when the tag was created.

updatedAt
string

Timestamp of when the tag was last updated.

Request samples

Content type
application/json
{
  • "name": "my_tag_2",
  • "entryKeys": [
    ],
  • "category": "Web"
}

Response samples

Content type
application/json
{
  • "id": "5e2996645a463ed6feabdebc",
  • "name": "my_tag_2",
  • "entryKeys": [
    ],
  • "category": "Web",
  • "createdAt": "2020-01-23T12:49:40.376Z",
  • "updatedAt": "2020-01-23T17:22:05.276Z"
}

Delete a tag by id.

Permission Requirements(Personal access tokens):

  • delete_tags_screenshots

Delete a single tag in a project with this endpoint. Associated screenshots will be deleted. The API will identify your project and authenticate the token and then return the tag whose id is specified in the url denoted by tagId.

Authorizations:
apiAccessToken
path Parameters
tagId
required
string
Example: 5fd77160c876c25340b17404

Unique identifier of a tag

query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Responses

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "DELETE");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/tags/%7BtagId%7D?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "X-Personal-Access-Token: SOME_STRING_VALUE");
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "message": "Error message!"
}

Screenshots

Operations associated with screenshots. Please see these guides for more information regarding screenshots

Screenshot Hashes

If you want to save time and bandwidth you can reduce the amount of screenshot uploads by checking the sha1 hash property of an already uploaded screenshot to see if your local file is different and only upload if thats the case. But be aware that the sha1 hash is only available for screenshots uploaded after 15. Nov. 2023.

The sha1 hash is stored in hex format and you could generate the hash locally in nodejs with the following code:

const Crypto = require('crypto');
const fs = require('fs');

const hashSum = Crypto.createHash('sha1');
const buffer = fs.readFileSync('/path/to/your/screenshot');
hashSum.update(buffer);

const hex = hashSum.digest('hex');
return hex;

Uploading screenshot

Permission Requirements(Personal access tokens):

  • upload_screenshots

Upload screenshots to a project using this endpoint. Send a POST request to https://api.applanga.com/v1/api/screenshots?app={app_id} with a FormData containing two keys data and file. The API will identify your project and authenticate the token. If your request is authorized the screenshot will be uploaded to your app and a json object describing the changes will be returned. Otherwise you will receive an http error.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: multipart/form-data

Note: the useOCR option which enables the detection of string positions on the image is no longer supported. String postions on images should be managed on the Applanga dashboard. Find out more information on how to manage screenshots from the dashboard here.

object

Object containing screenshot data.

file
string <binary>

Image file to upload

Responses

Response Schema: application/json
object

Request samples

Content type
multipart/form-data
{
  "data": {
    "screenTag": "tag99",
    "width": 600,
    "height": 400,
    "deviceModel": "test device model",
    "platform": "iOS",
    "operatingSystem": "iOS 16",
    "bundleVersion": "1.0.5",
    "deviceLanguageLong": "en",
    "useFuzzyMatching": true,
    "stringPositions": [
      {
        "key": "Key99",
        "x": 100,
        "y": 10,
        "width": 200,
        "height": 40
      },
      {
        "text": "myText",
        "x": 100,
        "y": 300,
        "width": 100,
        "height": 20
      }
    ]
  },
  "file": "<binary file content>"
}

Response samples

Content type
application/json
{ }

Requesting screenshot data.

Request screenshots in a project with this endpoint. The API will identify your project and authenticate the token and return all the screenshots in the Project.

Note: The generated url's are only working for 15 minutes for security reasons. Be aware that you have to download the images within that timeframe or redo the request to get newly generated urls.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
Array
url
string

Screenshot URL. Note: The generated URLs are only working for 15 minutes for security reasons. Be aware that you have to download the images within that timeframe or redo the request to get newly generated URLs.

originalName
string

Name for the screenshot file as uploaded.

mimetype
string
Enum: "image/jpeg" "image/png" "image/jpg"
object

Screenshot tag

object

More information about the screenshot.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/screenshots?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
[
  • {
    }
]

Mass delete screenshots for given queries

Permission Requirements(Personal access tokens):

  • delete_tags_screenshots

This endpoint deletes screenshots based on the specified parameters in the request body. The deletion is performed for screenshots that match all given criteria, where conditions are combined using AND operations. Additionally, it will silently delete tags associated with affected screenshots if no screenshots remain for those tags (only for those affected screenshots).

Deletions will only happen when we find matching screenshots. If no matching screenshots were found for a given query no screenshots or tags will be deleted.

The API will identify your project and authenticate the token.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
tagNames
required
Array of strings

Array of tag names of screenshots to be deleted (Only one of tagIds or tagNames is required)

tagIds
required
Array of strings

Array of tag ids of screenshots to be deleted. (Only one of tagIds or tagNames is required)

latestOnly
integer
Default: false
  • false: Only the screenshot variants that match specific languages, resolutions, tagCategories, os, and devices provided in the query. The deletion is performed for screenshots that match all given criteria, where conditions are combined using 'AND' operations.

  • true: Only the latest screenshot variant per tag and languages will be affected given the current query specifications. The latest implies the last added screenshot for per tag and per languages for the given query results.

    languages array is required when latestOnly is set to true.

languages
Array of strings

Array of language codes. ex) ["en", "de"].

Empty Array: Causes the endpoint to return 404 Not Found error.

Required: If any of the additional filter values, resolutions, os, device, versions, tagCategories are set, languages array is required.

Ommited: All languages options will be considered if no additional filter values are set.

resolutions
Array of strings

Array of resolution strings (ex. 100x100, width x height) of screenshots to be deleted. ex) ["100x200", "100x100"]

Empty Array: Causes the endpoint to return 404 Not Found error.

Ommited: All resolutions options will be considered.

tagCategories
Array of strings

Array of tag categories. ex) ["category1", "category2"]

Empty Array: Causes the endpoint to return 404 Not Found error.

Ommited: All tagCategories options will be considered.

os
Array of strings

Array of operating system names. ex) ["os1", "os2"]

Empty Array: Causes the endpoint to return 404 Not Found error.

Ommited: All os options will be considered.

devices
Array of strings

Array of devices. ex) ["device1", "device2"]

Empty Array: Causes the endpoint to return 404 Not Found error.

Ommited: All devices options will be considered.

versions
Array of strings

Array of version strings. ex) ["1.0", "1.2"]

Empty Array: Causes the endpoint to return 404 Not Found error.

Ommited: All versions options will be considered.

Responses

Response Schema: application/json
screenshotsDeletedCount
integer

Count of actual screenshots deleted

Request samples

Content type
application/json
{
  • "tagNames": [
    ],
  • "latestOnly": false,
  • "devices": [
    ],
  • "languages": [
    ],
  • "versions": [
    ],
  • "resolutions": [
    ],
  • "tagCategories": [
    ]
}

Response samples

Content type
application/json
{
  • "screenshotsDeletedCount": 2
}

Tags And Screenshot Deletion

Operations related to tags and screenshots deletion. Please see the delete tag by id and the mass screenshot delete api for more information.

Branches

Operations associated with branches. To learn more about branching please have a look at our Branching Documentation.

All availible API features can be extended with the "branch" parameter and will perform the same thing just on the specified branch. If no branch is specified the original Branch will be taken.

Create Branch

Permission Requirements(Personal access tokens):

create_branch

Use this endpoint to create a new branch in a branching Project. The API will identify your project and authenticate the token.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
name
required
string

Name of te branch.

sourceBranch
required
string

Indicates which branch to copy.

createInitialSettingsFile
boolean

If set to true the response of the request will contain a download link named settingsFileUrl for downloading the settingsfile for the new Branch

object

Object with the permissions for the branch. allowed permissions to set are 'readOnly' (default: false) and 'editableByTranslator' (default: true) (optional).

Responses

Response Schema: application/json
_id
string

Unique identifier of the object

name
string

Name of te branch.

object

Object with the permissions for the branch. allowed permissions to set are 'readOnly' (default: false) and 'editableByTranslator' (default: true) (optional).

settingsFileUrl
string

Only present if createInitialSettingsFile was true within the request. Will contain a download Url that is valid for 15 minutes for getting the settings file of the new Branch

Request samples

Content type
application/json
{
  • "name": "my_new_branch",
  • "sourceBranch": "608fbe4db764186e651f8e2b",
  • "permissions": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "608fbe4db764186e651f8e27",
  • "name": "my_new_branch",
  • "permissions": {
    }
}

Request Branch Info

Use this endpoint to fetch information regarding the branches that exists in a project. The API will identify your project and authenticate the token, then an object that contains the list of all branches for the given project is returned.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
defaultBranch
string

Id of the default branch.

Array of objects

List of all branches that exist in the project.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/branches?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "branches": [
    ],
  • "defaultBranch": "608fbe4db764186e651f8e2b"
}

Projects

Operations associated with projects.

Requesting list of projects

Permission Requirements(Personal access tokens):

  • get_project_list

Return list of projects the owner of the personal access token has access to. Authenticate via personal access token.

Authorizations:
apiAccessToken
query Parameters
userroles
Array of strings
Example: userroles=["admin","owner"]

When the parameter is used, only the projects in which the user has a specified role will be listed. The following roles are supported: 'owner', 'admin', 'manager', 'translator', 'tptadmin', 'tptservices' and 'tpttranslator'. By default all projects are returned.

header Parameters
Authorization
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For this GET request it is required to provide a Personal Access Token in Authorization header. To do so, set the Authorization header with your token.

Example: Authorization: Bearer 52b82d945c6115f2c4cc3844ee872f83.

Responses

Response Schema: application/json
Array
_id
string

Unique identifier of the object

name
string

Project name

role
string

The user role in the project

created
string

Timestamp of when the project was created.

team
string

Unique identifier of the object

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/projects?userroles=SOME_ARRAY_VALUE");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Requesting project API access token

Permission Requirements(Personal access tokens):

  • get_project_token

Return the project API access token. Authenticate via personal access token.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

header Parameters
Authorization
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For this GET request it is required to provide a Personal Access Token in Authorization header. To do so, set the Authorization header with your token.

Example: Authorization: Bearer 52b82d945c6115f2c4cc3844ee872f83.

Responses

Response Schema: application/json
accessToken
string

Api access token for the project.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/projects/token?app=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "accessToken": "YOUR-PROJECT-!-ACCESS-TOKEN"
}

Create sibling project

Permission Requirements(Personal access tokens):

  • create_sibling

Create a new project and based of another existing project. This allows you to copy settings, attributes and configs from the existing project into the new one. The API will identify your project and authenticate the token and create a new project that is a copy of the existing project.

By default an empty project is created when the request is completed with only a default language set for the new project. However it is possible to copy some more data, like the project settings, groups, languages, webhooks and other project settings. To enable this, some parameters described below should be set to true in the request body.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
projectName
required
string

This is required and must be set in the request body. It is the name that will be set for the new project.

identicalLanguages
boolean
Default: false

If set to true creates all the languages in the requested project in the new project.

identicalGroups
boolean
Default: false

If set to true creates all the groups in the requested project in the new project, else only a single default group(main) is created.

identicalProjectSettings
boolean
Default: false

If set to true, applies all the settings in the requested project in the new project.

identicalBranches
boolean
Default: false

If set to true creates all the branches in the requested project in the new project. Only applicable if the requested project is a branching project.

createInitialSettingsFile
boolean

If set to true the response of the request will contain a download link named settingsFileUrl for downloading the settingsfile for the new Project. If identicalBranches is also true settingsFileUrl will be a map of the branch name to the corresponding download url.

Responses

Response Schema: application/json
accessToken
string

Api access token for the newly created project.

string or object

Request samples

Content type
application/json
{
  • "projectName": "Sibling",
  • "identicalLanguages": true,
  • "identicalGroups": true,
  • "identicalProjectSettings": true,
  • "identicalBranches": true
}

Response samples

Content type
application/json
{
  • "accessToken": "YOUR-PROJECT-!-ACCESS-TOKEN"
}

Orders

Operations associated with orders.

Create a new order

Permission Requirements (Personal access tokens):

  • create_and_update_orders

The API will identify your project and authenticate the token and creates a new order based on the provided parameters. If you are using a Branching Project you also need to provide the branch_id as a parameter.

The order will be created if any translatable strings can be found for the given order creation parameters. If only some but not all of specified tags, groups or languages are found, the order will be created for the found scope as well. No order will be created if there are 0 words to translate.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

header Parameters
X-Personal-Access-Token
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
sourceLanguage
required
string

The source language ISO code. The language must exist in the project. The order will not be created if no value or invalid value is provided.

dueDate
string

Order delivery due date. If the provided date is in the past or less than a day ahead, it will be replaced with default value of 28 days

languages
required
Array of strings

An array of language ISO codes. These will be languages, into which the order will be translated. At least some of these languages must exist in the project and there must be an orderable content for at least one of them. Otherwise an error is returned (no order will be created).

stringOption
string
Default: "untranslated"

What type of strings should be selected for translation. The following values are available

all - all content

untranslated - all untranslated keys without Draft and without Target value (default)

sourceChanged - all keys with outdated Target values.

invalidTarget - all keys without Draft and without Target values, or with outdated Target values. Current Drafts will be overwritten.

needsTranslation - all keys with "Needs Translation" status.

needsReview - all keys with "Rejected" status.

needsTranslationOrRejected - all keys with "Needs Translation" or "Rejected" status.

<name_of_custom_status> - all keys with the particular custom status assigned.

withoutTarget - all keys which don't have Target values.

withTarget - all keys which have published values.

tooLong - all keys for which Target or Draft value exceeds the required Max Length

brief
string

Order brief text.

tags
Array of strings

Array of tag (or screenshot) names. Only the tagged keys will be included in the order scope. If additionally there is a source file created for each tag, each key must belong to exactly one tag (in such cases tags cannot "overlap").

includeNoTagKeys
boolean

Indicates if the strings without any assigned tag are in the order scope.

groups
Array of strings

Array of group names. Only strings in the indicated groups will be included in the scope. If the parameter is not specified, strings from all groups will be included in the scope. A maximum of 10 group names is allowed.

customBrief
Array of arrays

Array of custom order brief data consisting of pairs: { name: 'field name', value: 'field value' }. Please see Request custom order brief template for more details.

orderToCopy
string

translation scope is copied from a reference order. The order must be created for the same project. The option is useful, if exactly the same content needs to be included in a new order. If this option is used:

  • sourceLanguage value must match the reference order
  • Only dueDate, brief, notifyAddtionalUsers and customBrief fields will be taken into consideration. All other data will be taken over from the reference order
  • The reference order must have testing or done status (otherwise the same strings cannot be included into a new translation order, because they already have In-Order status)
languageToCopy
string

This option can only be used in combination with orderToCopy. The translation scope of the language specified in languageToCopy is re-used for another language in the same project. For that reason there is no restriction on status of the reference order and additionally the languages array must be provided.

notifyAddtionalUsers
Array of strings

Array of email addresses of users to be notified about order progress. These addresses must belong to the client team members.

ignoreOutdatedInActiveOrders
boolean

By default, the strings that are already in an order but they have become outdated (their source has changed) will be added to a new order. The exception is when sourceLanguage option and the project base language differ. Set the option to false to skip the strings with changed source..

Responses

Response Schema: application/json
_id
string

Unique identifier of the object

orderNumber
integer
sourceLanguage
string

Language code of the source language in the project.

sourceWordCount
number

Total number of words in the source language from all entries requested.

created
string

Timestamp of when the order was created.

updatedAt
string

Timestamp of when the order was last updated.

dueDate
string

Order delivery due date.

requester
string

Name of the person placing the order.

status
string
Enum: "draft" "requested" "created" "declined" "accepted" "processing" "testing" "done" "canceled" "onHold"

draft - A recently initiated order that is still in the creation phase.

requested - Relates to the quoting step of the translation ordering process. Please see here. This status means the order requester has requested a quote proposal for the order.

created - Relates to the quoting step of the translation ordering process. Please see here. This status means that a quote proposal has been created for the order and uploaded to Applanga, which the requester has to review.

declined - Relates to the quoting step of the translation ordering process. Please see here. This means the recent quote proposal created for the order was rejected by the requester.

accepted - Relates to the quoting step of the translation ordering process. Please see here. This means the requester accepts the recent quote proposal.

processing - This means the translation process has started.

testing - Some orders can be marked with the status 'testing' when the translations are delivered instead of done. The translations have been delivered, and testing is in progress. The strings belonging to this order no longer have 'In Order' status.

done - The translations have been delivered, and the order is completed.

canceled - The order was canceled.

onHold - Some orders have automated configurations that send them directly to translation. Sometimes a config misalignment could occur requiring review from an Applanga admin. In this case, the order status is automatically set to this status.

tags
Array of strings

List of used tag ids to filter by

includeNoTagKeys
boolean

Order includes all keys that are not Tagged

object

Request samples

Content type
application/json

In this sample request a new order is created based on scope of de language in existing order with id 64cb9e7c8bc9574c49de627f. The source language is en to be translated into fr-CA and es-MX languages in the same project.

{
  • "sourceLanguage": "en",
  • "languages": [
    ],
  • "orderToCopy": "64cb9e7c8bc9574c49de627f",
  • "languageToCopy": "de"
}

Response samples

Content type
application/json
{
  • "order": {
    }
}

Request list of all project orders

Use this endpoint to fetch all the orders in a project. The API will identify your project and authenticate the token and return a list of all orders for the project.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
Array
id
string

Unique identifier of the object

orderNumber
integer
sourceLanguage
string

Language code of the source language in the project.

created
string

Timestamp of when the order was created.

updatedAt
string

Timestamp of when the order was last updated.

dueDate
string

Order delivery due date.

requester
string

Name of the person placing the order.

status
string
Enum: "draft" "requested" "created" "declined" "accepted" "processing" "testing" "done" "canceled" "onHold"

draft - A recently initiated order that is still in the creation phase.

requested - Relates to the quoting step of the translation ordering process. Please see here. This status means the order requester has requested a quote proposal for the order.

created - Relates to the quoting step of the translation ordering process. Please see here. This status means that a quote proposal has been created for the order and uploaded to Applanga, which the requester has to review.

declined - Relates to the quoting step of the translation ordering process. Please see here. This means the recent quote proposal created for the order was rejected by the requester.

accepted - Relates to the quoting step of the translation ordering process. Please see here. This means the requester accepts the recent quote proposal.

processing - This means the translation process has started.

testing - Some orders can be marked with the status 'testing' when the translations are delivered instead of done. The translations have been delivered, and testing is in progress. The strings belonging to this order no longer have 'In Order' status.

done - The translations have been delivered, and the order is completed.

canceled - The order was canceled.

onHold - Some orders have automated configurations that send them directly to translation. Sometimes a config misalignment could occur requiring review from an Applanga admin. In this case, the order status is automatically set to this status.

tags
Array of strings

List of used tag ids to filter by

includeNoTagKeys
boolean

Order includes all keys that are not Tagged

languages
Array of strings

List of languages included in the order.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/order?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
[
  • {
    }
]

Request an order by id

Use this endpoint to fetch a single order by id. The API will identify your project and authenticate the token and return details of the requested order.

Authorizations:
apiAccessToken
path Parameters
orderId
required
string
Example: 5fd77160c876c25340b17404

Unique identifier of an order

query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
id
string

Unique identifier of the object

orderNumber
integer
sourceLanguage
string

Language code of the source language in the project.

created
string

Timestamp of when the order was created.

updatedAt
string

Timestamp of when the order was last updated.

dueDate
string

Order delivery due date.

requester
string

Name of the person placing the order.

status
string
Enum: "draft" "requested" "created" "declined" "accepted" "processing" "testing" "done" "canceled" "onHold"

draft - A recently initiated order that is still in the creation phase.

requested - Relates to the quoting step of the translation ordering process. Please see here. This status means the order requester has requested a quote proposal for the order.

created - Relates to the quoting step of the translation ordering process. Please see here. This status means that a quote proposal has been created for the order and uploaded to Applanga, which the requester has to review.

declined - Relates to the quoting step of the translation ordering process. Please see here. This means the recent quote proposal created for the order was rejected by the requester.

accepted - Relates to the quoting step of the translation ordering process. Please see here. This means the requester accepts the recent quote proposal.

processing - This means the translation process has started.

testing - Some orders can be marked with the status 'testing' when the translations are delivered instead of done. The translations have been delivered, and testing is in progress. The strings belonging to this order no longer have 'In Order' status.

done - The translations have been delivered, and the order is completed.

canceled - The order was canceled.

onHold - Some orders have automated configurations that send them directly to translation. Sometimes a config misalignment could occur requiring review from an Applanga admin. In this case, the order status is automatically set to this status.

tags
Array of strings

List of used tag ids to filter by

includeNoTagKeys
boolean

Order includes all keys that are not Tagged

languages
Array of strings

List of languages included in the order.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/orders/%7BorderId%7D?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
{
  • "id": "650c075c9db5e5ab0e661277",
  • "orderNumber": 3926,
  • "sourceLanguage": "en",
  • "created": "2023-12-26T14:09:49.556Z",
  • "dueDate": "2023-11-28T12:56:46.510Z",
  • "requester": "Jane Doe",
  • "status": "processing",
  • "languages": [
    ]
}

Request custom order brief template

The Custom Order Brief feature is currently only available for Enterprise plans. It enables to pass on additional order brief information in a predefined, structured way in a new order request.

The same custom order brief template will be returned for all projects and branches in a particular team. Using branch parameter is possible, but not necessary.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
Array
name
required
string

Field name to be used in new order request. In case the field name is not matched to any in the template, it will be ignored, or if the order brief template contains a mandatory fields that is not provided, an error will be returned.

type
required
string

The field can be of type: - text - a free text value is accepted - selection - only values predefined in selectionList are accepted.

selectionList
string

List of predefined values to be used when the field type is selection.

defaultValue
string

If no value is provided, this will be the value used in the custom order brief.

placeholder
string

Placeholder that defines the value.

mandatory
string

A valid value for this field must be provided: non-empty text or item from selectionList. In case of conditional fields, the value must be provided only if the condition is fulfilled.

object

Some fields are used in order brief conditionally. For simplicity the conditions are only one level deep (a conditional field is not included in condition of another field).

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/orderBriefTemplate?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json

In the below example there are 4 custom order brief fields defined. The example custom brief should be interpreted as follows:

  1. Project name is a mandatory text field. The non-empty value must be provided, otherwise the order will not be created.
  2. Project type is a selection field. The value in the new order request must match one of the provided selection options. If not provided or not matching, the default value translation will be used.
  3. Review rounds is a conditional text field and can only be used when review value is selected in Project type field.
  4. Screens Review is a conditional and mandatory selection field. If the condition is fulfilled, the field must be provided. In the example, the field is necessary if the value of Project name contains the text screen. The field doesn't have a default value, so if no value or invalid value is provided, the order is not created.

Note The field names and values are case-sensitive, so in particular the custom order brief names in new order request must be exactly as in the response here.

Example values that can be put in customBrief array in a new order creation request based on the below example order brief template:

>     ...
>     "customBrief":[
>         { "name": "Project name", "value": "My app translation project" },
>         { "name": "Project type", "value": "translation" }
>         { "name": "Screens Review", "value": "Yes" }
>     ],
>     ...
[
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Webhooks

Operations associated with orders. Learn more about webhooks here.

Create or update project webhooks

Permission Requirements(Personal access tokens):

  • create_and_update_webhooks

Use this endpoint to create a new webhook and update existing webhook. When it is an update, the webhookEndpointId parameter should be set, where webhookEndpointId is the id of the webhook that should be updated. A webhook's id can be copied from the webhook modal in the project settings.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

webhookEndpointId
string

This should be set when a webhook should be updated, set the id of the webhook that should be updated here.

header Parameters
X-Personal-Access-Token
required
string
Example: 52b82d945c6115f2c4cc3844ee872f83

For POST requests it is recommended and in some cases required to provide a Personal Access Token. To do so, set the X-Personal-Access-Token header with your token.

Example: X-Personal-Access-Token: 52b82d945c6115f2c4cc3844ee872f83.

Request Body schema: application/json
eventType
string
Enum: "TranslationChanges" "StatusChanges" "AllChanges"

Refers to the activities that will trigger a webhook.

TranslationChanges: This refers to changes related to the translation entries. Whenever a translation entry is created, updated, or deleted, it triggers a translation change event.

StatusChanges: This event occurs when the status of a translation entry is changed.

AllChanges: When this option is selected, the webhook is triggered for any change related to translation entries. This includes all events described in Translation Changes and Status Changes, as well as other activities such as updating translation drafts, tagging entries, linking entries, locking entries, etc.

disabled
boolean
Default: false

This is an optional parameter, if set to true, Applanga will no longer send requests to the configured url. This is false by default when.

url
string

This is a required parameter when creating a new webhook. It is the endpoint that Applanga will make a request when needed. A valid https url is expected here

httpMethod
string
Enum: "get" "post"

This is a required parameter when creating a new webhook. Only get and post http methods are allowed, setting any other value would result in an error response.

Array of objects

It is an array of objects representing HTTP headers, where each object must contain the following fields key, value and optionally description.

object

When the httpMethod is set to post, the content will be set in the webhook request, and in the webhook request a Content-Type header will be set to the value of contentType.

Responses

Response Schema: application/json
_id
string

Unique identifier of the object

disabled
boolean
Default: false

Indicates if the webhook is disabled or not. If set to true then Applanga will no longer send requests to the configured url.

url
string

It is the endpoint that Applanga will make a request when needed.

httpMethod
string
Enum: "get" "post"
Array of objects

It is an array of objects representing HTTP headers, where each object contains the following fields key, value and optionally description.

object

When the httpMethod is set to post, the content will be set in the webhook request, and in the webhook request a Content-Type header will be set to the value of contentType.

userId
string

Id of the user thatcreated teh webhook.

eventType
string
Enum: "TranslationChanges" "StatusChanges" "AllChanges"

Refers to the activities that will trigger a webhook.

TranslationChanges: This refers to changes related to the translation entries. Whenever a translation entry is created, updated, or deleted, it triggers a translation change event.

StatusChanges: This event occurs when the status of a translation entry is changed.

AllChanges: When this option is selected, the webhook is triggered for any change related to translation entries. This includes all events described in Translation Changes and Status Changes, as well as other activities such as updating translation drafts, tagging entries, linking entries, locking entries, etc.

Request samples

Content type
application/json
{
  • "httpMethod": "post",
  • "headers": [
    ],
  • "body": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "6581afcfd90bf002ebc4f4b7",
  • "created": "2023-12-19T14:59:27.607Z",
  • "httpMethod": "post",
  • "body": {
    },
  • "headers": [
    ],
  • "disabled": false,
  • "eventType": "TranslationChanges",
  • "userId": "5fd7709070b8bd529ed8f3a8"
}

Request list of all project webhooks

Use this endpoints to fetch webhooks configured in a project. The API will identify your project and authenticate the token and return all the webhooks in the project.

Authorizations:
apiAccessToken
query Parameters
app
required
string
Example: app=608fbe4db764186e651f8e2b

This is the id of the project that the translations should be uploaded to. It is required for both legacy and branching projects.

branch
string
Example: branch=608fbe4db764186e651f8e2b

If you are using a branching project and want to specify the branch, then this parameter should be set to the id of the branch. You can get the branch id either in the settings of your project or request it via an api route (see Requesting Branches) or for more information on branching have a look at our branching documentation).

All available Api features can be extended with the "branch" parameter and will perform the requested action on the specified branch. If there is no branch parameter in the request, the action is performed on the "main" branch.

Responses

Response Schema: application/json
Array
_id
string

Unique identifier of the object

disabled
boolean
Default: false

Indicates if the webhook is disabled or not. If set to true then Applanga will no longer send requests to the configured url.

url
string

It is the endpoint that Applanga will make a request when needed.

httpMethod
string
Enum: "get" "post"
Array of objects

It is an array of objects representing HTTP headers, where each object contains the following fields key, value and optionally description.

object

When the httpMethod is set to post, the content will be set in the webhook request, and in the webhook request a Content-Type header will be set to the value of contentType.

userId
string

Id of the user thatcreated teh webhook.

eventType
string
Enum: "TranslationChanges" "StatusChanges" "AllChanges"

Refers to the activities that will trigger a webhook.

TranslationChanges: This refers to changes related to the translation entries. Whenever a translation entry is created, updated, or deleted, it triggers a translation change event.

StatusChanges: This event occurs when the status of a translation entry is changed.

AllChanges: When this option is selected, the webhook is triggered for any change related to translation entries. This includes all events described in Translation Changes and Status Changes, as well as other activities such as updating translation drafts, tagging entries, linking entries, locking entries, etc.

Request samples

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "GET");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api.applanga.com/v1/api/webhooks?app=608fbe4db764186e651f8e2b&branch=608fbe4db764186e651f8e2b");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "Authorization: Bearer REPLACE_BEARER_TOKEN");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

CURLcode ret = curl_easy_perform(hnd);

Response samples

Content type
application/json
[
  • {
    }
]