Introduction

The Avilinga API provides functionality to automate management of translation jobs including creation and retrieval. The API is implemented over HTTPS using POST requests. All responses are JSON formatted.

All communications are UTF-8 encoded.

API calls are stateless. Each call should always include a standard set of authentication credentials.

Each client is assigned an API endpoint depending on environment functionality.

The following variables are used throughout the API documentation:

  • $ROOT – the API endpoint, for example https://example.ld.ai/api
  • $USERNAME – assigned client username
  • $PASSWORD – assigned client password
  • $LANGUAGE – iso639-1 or iso639-3 language code or culture name in xx_XX format case insensitive
  • $RESPONSE_CODE – one of "OK", "ERROR" or "ACCESS_DENIED" constants

Each of the delivered ZIP files contains a folder for each translated language. Each folder contains all translated files (full path included). Folders for translated languages named with iso639-3 code or culture code in the case when iso639-3 is not available.

All DATETIME request and response parameters should have the YYYY-MM-DD HH:MM:SS format.

Languages

Content is to be translated from a single source language into one or multiple target languages.

Source and target language tables contain separate, differing values as sources are generic languages (e.g English or Chinese) while targets can be specific varietals, (e.g. UK English or Traditional Chinese)

Every language is described with a unique and non-changing identifier, either by ISO 639-1 (if exists or null), ISO 639-3 (if exists or null) or culture code (a combination of ISO 639-1 + ISO 3166-1 in form of xx_XX).

API call list

  • $ROOT/config gets custom user configuration options
  • $ROOT/languages/list gets a list of source and target languages and enabled language pairs
  • $ROOT/languages/check checks if language pair is enabled for client account
  • $ROOT/projects/list gets a list of ongoing projects
  • $ROOT/projects/details queries project details
  • $ROOT/projects/add adds a new project
  • $ROOT/projects/files/add adds a new file to an uploading project
  • $ROOT/projects/references/add adds a new reference file to an uploading project
  • $ROOT/projects/run runs a project
  • $ROOT/projects/approve approves a project quotation
  • $ROOT/projects/close closes a project
  • $ROOT/projects/retrieved marks a project target language as retrieved
  • $ROOT/projects/delete deletes a project, if possible
  • $ROOT/turnarounds/list gets a list of turnarounds with upcoming job completion dates

Config

This method returns custom user configurations including available cost centres, workflow methods, and turnarounds. These settings can be customized by your Avilinga admin.

URL

$ROOT/config

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
agent: STRING                     (optional) the name of the agent

JSON response

{
  "status": $RESPONSE_CODE,
  "config": {
    "cost_centers": [
      {
        "id": INT,                cost centre id
        "name": STRING,           cost centre name/description
        "default": 1|0            one of them may be default
      }
    ],
    "turnarounds": [
      {
        "id": INT,                turnaround id
        "name": STRING,           turnaround name/description
        "default": 1|0            one of them may be default
      }
    ],
    "workflows": [
      {
        "id": INT,                workflow id
        "name": STRING,           workflow name
        "default": 1|0            one of them may be default
      }
    ],
    "approve_quote_default": 1|0  default job approval setting
  }
}

Enabled languages

This method returns all the possible source and target languages plus the enabled language combinations on your Avilinga account. Language pairs may be added by speaking to your Avilinga representative.

URL

$ROOT/languages/list

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD

JSON response

{
  "status": $RESPONSE_CODE,
  "source_languages": [
    {
      "id": INT,
      "name": STRING,
      "iso639_1": CHAR[2],
      "iso639_3": CHAR[3],
      "locale": CHAR[5]
    }
  ],
  "target_languages": [
    {
      "id": INT,
      "name": STRING,
      "iso639_1": CHAR[2],
      "iso639_3": CHAR[3],
      "locale": CHAR[5]
    }
  ],
  "language_pairs": [
    {
      "source_language_id": INT,
      "target_language_id": INT,
      "language_group_ids": STRING	comma separated list of integers
    }
  ],
  "language_groups": [
    {
      "id": INT,
      "name": STRING
    }
  ]
}

Language check

This method checks if source and target languages are enabled on your Avilinga account. The endpoint can accept source and target languages in ISO 639-1, ISO 639-3 or locale standard (ISO 639-1 + ISO 3166-1 in form of xx_XX). Values can be written any case. Enabled language pairs may change depending on client configuration.

URL

$ROOT/languages/check

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
source_language: $LANGUAGE
target_languages: [
  $LANGUAGE
]

JSON response

{
  "status": $RESPONSE_CODE,
  "source_language": BOOLEAN,
  "target_languages": {
    requested_target_language: BOOLEAN
  },
  "language_pairs": {
    requested_target_language: BOOLEAN
  }
}

List projects

Queries all ongoing open translation projects that $USERNAME has access to.

Project workflow is as follows:

  1. NEW: project has just been submitted via API, waiting to be processed at Avilinga end
  2. QUOTE: project has been pre-processed, with quote generated at Avilinga end. This stage will be skipped if the job is approved automatically (depending on client settings)
  3. ACTIVE: project is being translated at Avilinga end
  4. PARTIALLY-COMPLETED: one or more of project’s target languages are finished (see projects[].metrics[].completed for appropriate target_language to get status of project’s target language).
  5. COMPLETE: project finished, waiting to be retrieved

URL

$ROOT/projects/list

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD

JSON response

{
  "status": $RESPONSE_CODE,
  "projects": [
    {
      "id": INT,                            project id
      "description": STRING,                project description
      "source_language_iso639_3": CHAR[3],
      "target_languages_iso639_1": CHAR[2],
      "target_languages_iso639_3": CHAR[3],
      "target_languages_locale": CHAR[5],
      "status": "NEW" | "QUOTE" | "ACTIVE" | "COMPLETE" | "PARTIALLY-COMPLETED",
      "cost_center_id": INT,                see config API
      "metrics": [
        {
          "target_language_iso639_1": CHAR[2],
          "target_language_iso639_3": CHAR[3],
          "target_language_locale": CHAR[5],
          "complete": 1|0,
          "retrieved": 1|0,
          "word_count": [
            {
              "class": STRING,              e.g. ICE or Non-Matching
              "words": INT,                 number of words in class
              "price_currency": CHAR[3],
              "price_word": FLOAT,
              "price_total": FLOAT          price_word * words
            }
          ],
          "words": INT,                     total number of words
          "price_currency": CHAR[3],
          "price_total": FLOAT,
          "retrieval_url": STRING,          direct URL to retrieve completed
                                            file or files (in a ZIP),
                                            if the project is
                                            PARTIALLY-COMPLETED or COMPLETE
        }
      ],
      "turnaround_id": INT,                 see config API
      "created_by": {
        "email": STRING,
        "first_name": STRING,
        "last_name": STRING,
      },
      "created_utc": DATETIME,
      "due_utc": DATETIME                   requested delivery time
    }
  ]
}
Metrics and pricing information could be absent depending on project status.

Query project details

Queries one project that $USERNAME has access to.

This function is similar to the List Projects API call except it is limited to one project only.

URL

$ROOT/projects/details

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT

JSON response

{
  "status": $RESPONSE_CODE,
  "projects": [
    {
        refer to List Projects API call
    }
  ]
}

Add project

Submits a new translation project

Projects which are loaded with source files are automatically launched. Projects loaded without source files should have source files added later, and then subsequently launched using $ROOT/projects/run.

URL

$ROOT/projects/add

Method

POST (multipart/form-data)

Request parameters

username: $USERNAME
password: $PASSWORD
name: STRING                project name
group: STRING               (optional) project group name
description: STRING         project description (can be empty string)
source_language: $LANGUAGE
target_languages: [
  $LANGUAGE
]
file: [
  file                      file (can be zipped into one archive)
                            to be translated
]
cost_center_id: INT         select from config options 
turnaround_id: INT          select from config options
workflow_id: INT            select from config options
delay: 1|0                  (optional) delay project launch until
                            $ROOT/projects/run API call
due_utc: DATETIME           (optional) requested delivery time
auto_approve: 1|0           auto approve quote
cms_type: STRING            (optional) the name of CMS which is using API

JSON response

{
  "status": $RESPONSE_CODE,
  "project_id": INT         created project ID
}

Add files to project

Add new source files to the project

Only jobs that have been uploaded without files and those which have not yet been run can be affected by this endpoint.

URL

$ROOT/projects/files/add

Method

POST (multipart/form-data)

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT             project id
file: file                  file or files (in a ZIP archive) to be translated

JSON response

{
  "status": $RESPONSE_CODE,
  "project_file_id": INT    appended project_file_id
}

Add reference files to project

References are optional image files for translator reference.

URL

$ROOT/projects/references/add

Method

POST (multipart/form-data)

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT                   project id
file: file                        file to be appended
referenced_project_file_id: INT   (optional) if referenced project file
                                  is not set, reference file
                                  will be used for all project files

JSON response

{
  "status": $RESPONSE_CODE
}

List turnarounds

Queries all turnarounds with upcoming dates of project completion based on SLA based on project ID or given details. Best practice is to call it before Run project or Approve project.

URL

$ROOT/turnarounds/list

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT
target_languages: [
  $LANGUAGE                      (optional)
]

or

username: $USERNAME
password: $PASSWORD
costcenter_id: INT
source_language: $LANGUAGE
target_languages: [
  $LANGUAGE
]
wordcount: INT                   (optional) wordcount to calculate,
                                 min_due_utc field, default 0

JSON response

{
  "status": $RESPONSE_CODE
  "turnarounds": [
    {
      "id": INT,                 turnaround id
      "name": STRING,            turnaround description
      "rush_level": INT,         0 for Normal, 1 for Rush
      "min_due_utc": DATETIME    upcoming date of project completion
                                 for current turnaround and given wordcount
    }
  ],
  "working_hours": [
    {                            working hours (see note below)
      "utc_from": DATETIME,      date and time of the period
      "utc_to": DATETIME,        this field can be absent
      "days": {                  object of weekdays
        "0": [                   0 is Sunday
          {
            "utc_from": STRING,  time in "H:MM" 24-hour format
            "utc_to": STRING     time in "H:MM" 24-hour format
          }
        ],
        "1": ...                 1 is Monday, etc
      }
    }
  ]
}
Note on the working_hours array: the array represents Avilinga working hours to calculate valid delivery time. The array contains one to several objects describing the time periods. The days object contains one to seven objects with names from 0 to 6, representing the working weekdays. 0 is Sunday. utc_from and utc_to of each day object contains an array with periods of working hours.

Run project

Run project that was originally uploaded without files.

If no files have been subsequently uploaded to the project, API request fails.

URL

$ROOT/projects/run

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT or [INT]
turnaround_id: INT          (optional) if initial one should be changed
due_utc: DATETIME           (optional) requested delivery time

JSON response

{
  "status": $RESPONSE_CODE
}

Approve project

Approves a project that has status: QUOTE

URL

$ROOT/projects/approve

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT
due_utc: DATETIME           (optional) requested delivery time
turnaround_id: INT          required only if due_utc field is present

JSON response

{
  "status": $RESPONSE_CODE
}

Download target file(s)

Downloads target files. It can contain all files if the project is completed or some of them in the case if the project is completed partially.

Data about completed target languages is available in $ROOT/projects/details or $ROOT/projects/list in the metric.completed field.

The address of this endpoint must be obtained from $ROOT/projects/details or $ROOT/projects/list retrieval_url field.

URL

$ROOT/project/{project_id}/download

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD

Binary response

zip file with request

or JSON response

{
  "status": "ACCESS_DENIED" | "ERROR"
}

Mark target language as retrieved

After target zip file of a partially completed project is downloaded, target language can be marked as "retrieved". When target language will be marked as "retrieved", its "retrieved" field will contain 1 on calling $ROOT/projects/details or $ROOT/projects/list API request.

URL

$ROOT/projects/retrieved

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT
target_languages: [
  $LANGUAGE
]

JSON response

{
  "status": $RESPONSE_CODE
}

Close project

Closes a finished project that has COMPLETE status to put it into Archive.

URL

$ROOT/projects/close

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT
target_languages: [
  $LANGUAGE
]

JSON response

{
  "status": $RESPONSE_CODE
}

Delete project

Deletes a project that has NEW or QUOTE status.

URL

$ROOT/projects/delete

Method

POST

Request parameters

username: $USERNAME
password: $PASSWORD
project_id: INT
target_languages: [
  $LANGUAGE
]

JSON response

{
  "status": $RESPONSE_CODE
}
Avilinga API Specification
Introduction Languages API call list Config Enabled languages Language check List projects Query project details Add project Add files to project Add reference files List turnarounds Run project Approve project Download target file(s) Mark as retrieved Close project Delete project