1. Who is this document for?

This document is aimed at developers building connections to LocHub via the TAPICC API, and other interested parties in the LocHub implementation of the TAPICC specification.

The present document aims to provide developers some context and advice on implementing the workflows supported by TAPICC when building an integration with the LocHub TAPICC API .

This guide does not provide reference documentation about the API, which can be found at /docs of any LocHub instance.

2. What is TAPPIC?

The Translation API Cases and Classes (TAPICC) initiative is a collaborative, community-driven, open-source project to advance API standards for multilingual content delivery. The overall purpose of this initiative is to provide a metadata and API framework on which users can base their integration, automation, and interoperability efforts.
The current published standard for the TAPICC API is version 0.0.7.

TAPICC is a new standard elaborated by several working groups to analyze and standardize the "content transformation" business. Focusing primarily on translations.

The standard follows a set of guiding principles:

  • TAPICC is about the exchange of information between system processes in the content industry.

  • TAPICC does not replace CMSs or TMSs.

  • Document, User, Role, and Workflow management are out of scope of the standard.

    • the TAPICC model works with immutable snapshots of documents.

    • TAPICC does not specify any User or Role model, nor any Authorization policy.

    • TAPICC does not dictate what the next step after a task has been completed is. This is left to the collaborating parties.

    • TAPICC does not replace or overlap with other initiatives in the field of content exchange formats, nor uniform Content APIs such as CMIS.

    • TAPICC promotes and supports but does not impose standardization of the translatable payload.

    • TAPICC does not interpret payloads, i.e. does not provide word counts, does not transform content.

2.1. Support for Industry Standards

The XML Localization Interchange File Format (XLIFF) standard is a common format used to standardize the way localizable data is passed between tools. XLIFF files are supported by the LocHub TAPICC API implementation in so far as they can be uploaded and downloaded, just like any other file format, such as a source or bitext.

3. Workflow for a Translation

3.1. Roles

There are two main actors in the various use cases for the LocHub TAPICC API implementation:

Content Owner
The Content Owner owns the content to be processed. They manage and configure the translation Job, it’s Tasks, and related Inputs. A Content Owner, for example, could be a marketing consultant who needs some promotional documents translated, or a website content editor who needs web pages translated for international customers.

Service Provider
The Service Provider supplies content processing services. They access the source and supporting documents and perform translation operations. A Service Provider in this context can be, for example, a Language Service Provider (LSP).

Service Providers own the Deliverables associated with a Task. These are the results of a translation action.

3.2. Authentication and Authorization

All TAPICC endpoints require an OAuth2 bearer token.

Authentication and Authorization are not part of the scope of this document.

3.3. Simple TAPICC Entity Relationship Diagram

diag 89c41770dc1b50355cc4b334e6cda112
Figure 1. Simple TAPICC ERD

3.4. LocHub TAPICC Implementation

LocHub aims to enable large-scale enterprise translation projects to be fully automated and independent from tooling. The project goals are to reduce workload through automation, thus increasing throughput of translation tasks while maintaining clear and manageable oversight and control.

The LocHub project embraces the TAPICC initiative and seeks to contribute to the standard. In doing so, enabling other TAPICC integrations to interact with Xillio LocHub out of the box.

Currently, LocHub implements a fraction of the TAPICC v0.0.7 specification:

  • Only the translation workflow is implemented

  • Webhooks are not implemented, therefore polling must be used to identify changes to Jobs and Tasks.

  • The TIPP endpoint is not supported since the REST endpoint can provide better information.

The TAPICC standard defines a list of file types to describe input files and deliverables files. It is the Content Owner’s responsibility to ensure the file type specified corresponds to the actual file uploaded. LocHub does not validate it is correct or meaningful.

3.4.1. Successful Translation Flow

diag cb0e60ac7b1c586dec2ba0701f66e0ff
Figure 2. Successful Translation Sequence Diagram

3.4.2. Create Job

Content Owner performs this action

A Job is the owner of resources such as translation source documents and reference documents (Inputs), translated documents (Deliverables), and their associated Tasks.

  • A successful response returns the details of the newly created Job, including the JobId identifier.

  • A Job may have one or more Tasks, Inputs, and or Deliverables, related to it. Refer to Simple TAPICC Entity Relationship Diagram.

Endpoint and Expected Response Code
    POST http://lochub.xillio.com/tapicc/jobs
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>  (1)
    Content-Type: application/json
    Accept: application/json
1 See LocHub Reference Manual on how to obtain an access token.
Body
    {
        "submitter": "mycompany.com/123456", (1)
        "name": "the name of the Job",
        "description": "detailed description of the Job",
        "externalId": "123-your-identifier",
        "dueDate": "2019-08-27T12:07:48.575Z" (2)
    }
1 The submitter field is a free form reference to a user on the originating system, not the user logged in the TAPICC API.
2 All dates must be ISO 8601 compliant, and time zone of "UTC" "Z time" or "Zulu Time".

3.4.3. Upload Content and Create Input

Content Owner performs this action

The main purpose of LocHub, and it’s TAPICC API implementation, is to easily facilitate the management of the file translation process (i.e. documents, images or videos) from source language to one or more target languages.

Inputs represent the files, provided by the Content Owner, that feed into a translation pipeline. An input is not always the source of the translation material. Depending on the case, it could be some related content such as (but not limited to):

  • Supporting document with instructions for the translator.

  • A source file to be translated like a Word document.

  • A translation memory to be used.

  • A glossary.

An Input maintains a number of other relationships such as their related Tasks, and Deliverables. There are also a number of optional properties that can be set such as the original file name and creation date.

For LocHub synchronisation, the fileType must be set to source.
Endpoint and Expected Response Code
    POST http://lochub.xillio.com/tapicc/inputs
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: multipart/form-data
    Accept: application/json
Table 1. Body Parts for multipart/form-data
Body part Value

jobId

1234

fileType

source

inputId

789

input

<file contents>

3.4.4. Create Task

Content Owner performs this action

It is recommended to create a Task for each Input (source document) that is to be translated. As a Task defines the discrete properties and state of the activity to be performed on a Input, this strategy allows finer granular control. It is possible to assign multiple Inputs to a Task, and this is may be required to provide supporting documents, but multiple source documents are discouraged since they would be treated as a unit, making the API less versatile.
Tasks also maintain a status flag of which there are a finite set of allowed values. Refer to the state transition diagram: Task States.

The scope of this document is only for the translation task type.
Endpoint and Expected Response Code
    POST http://lochub.xillio.com/tapicc/tasks
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
    {
        "jobId": "123",
        "inputIds": ["43", "12"],
        "type": "translation",
        "sourceLanguage": "en",  (1)
        "targetLanguage": "cz",  (2)
    }
1 Language codes must comply with IETF BCP47 standard tags.
2 Both sourceLanguage and targetLanguage values must be provided for a Task.

3.4.5. Confirm Task is Ready

Content Owner performs this action

To make a Task ready for processing by a Service Provider, it must have its status set to confirmed by the Content Owner. Before this happens the Service Provider should not operate on the task or its inputs.

At least one source file must be associated with a Task before its status can be confirmed.
Endpoint and Expected Response Code
    PATCH http://lochub.xillio.com/tapicc/tasks/{taskId}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
    {
        "status" : "confirmed"
    }

3.4.6. Start Tasks

Service Provider performs this action

When the Service Provider wants to start working on the task it updates its status to in_progress, optionally setting the assignedTo field with a free form reference to its internal user.

If the task is ill defined, for example because it is missing an input of type source, the Service Provider would set the tasks status to rejected and write the reason for rejection in the field note.

3.4.7. Upload Deliverables

Service Provider performs this action

Once a Service Provider has completed the content transformation of a Task Input, a Deliverable should be created and its content uploaded.

For LocHub synchronisation, the fileType must be set to source.
Endpoint and Expected Response Code
    POST http://lochub.xillio.com/tapicc/deliverables
    -------------------
    HTTP/1.1 201 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: multipart/form-data
    Accept: application/json
Table 2. Body Parts for multipart/form-data
Body part Value

jobId

1234

taskId

6543

fileType

source

inputId

789

deliverable

<file contents>

The part inputId is optional and declares this Deliverable a derivation of the given Input. For example this field would contain the id of the Input of type source that is the original of this translation. If the source document has been broken down in different parts as a result of the task, each part would be a Deliverable referencing the same Input.

3.4.8. Complete Task

Service Provider performs this action

When the Service Provider has finished uploading the Deliverables of a task, it sets the status of the task to completed. This communicates to the Content Owner that the task is not going to change and that the results are attached to it as Deliverables.

Endpoint and Expected Response Code
    PATCH http://lochub.xillio.com/tapicc/tasks/{taskId}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Body
    {
        "status" : "completed"
    }

3.4.9. Get Deliverables

Content Owner performs this action

Once the Service Provider has uploaded their completed files, and set the Task status to completed, the Content Owner is able to download the Deliverables.

Get Deliverable Ids

To access Deliverables for a Task, the Content Owner must first get the metadata about the Task which includes a list of deliverable identifiers. Using these ids, they can then request the metadata and content of a Deliverable (i.e. the translated document).

Endpoint and Expected Response Code
    GET http://lochub.xillio.com/tapicc/tasks/{taskId}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json
Get Deliverable Metadata
Endpoint and Expected Response Code
    GET http://lochub.xillio.com/deliverables/{deliverableId}
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Content-Type: application/json
    Accept: application/json

3.4.10. Download Deliverable Contents

Content Owner performs this action

Once the Content Owner has the Deliverable metadata, then it can request their associated content. Each request represents a request to download an individual file.

Endpoint and Expected Response Code
    GET http://lochub.xillio.com/deliverables/{deliverableId}/file
    -------------------
    HTTP/1.1 200 The requested resource
Headers
    Authorization: Bearer <<YOUR_TOKEN>>
    Accept: application/octet-stream

3.5. Other API Operations

The API exposes endpoints to delete all entities mentioned here, which can be used by the creator (or owner) of the entity. An entity owning or referenced by other entities cannot be deleted. For example, to delete a job the following operation sequence must be observed:

  1. update all tasks to state cancelled;

  2. delete the Deliverables of the Job;

  3. delete the Inputs of the Job;

  4. delete the Tasks of the Job.

During deletion the tasks will become ill defined.

3.6. Alternate Sequences

There various possible scenarios that can be illustrated as alternate use cases. The following diagram describes them at a high level.

diag de442103fd910893981fca48be6c4ecb
Figure 3. Alternate Sequence Diagram

3.7. Task States

The following state transition diagram illustrates the possible states that a Task can have, and the possible transitions.

diag fd1694d0501983c086e6c6e53a3ae89a
Figure 4. Task State Transition Diagram