Text United Translation API


box Authentication and authorization

An API request must be sent over HTTPS and must include a Company ID and API Key. Basic Authentication is used to submit these details, and the Company ID and the API key should be used as parameters (instead of a user name and a password). The authentication values are contained in the http header as unencrypted base64-encoded text. That way all the communication to Text United API server is carried out over SSL connections.

Curl example

C# example


box XML document processing via API

The xml processing filter used in API methods differs from the xml filter used by default by the desktop and web app.
These exceptions apply only to the files that are uploaded via API:

  • CDATA elements that hold translatable content will be processed for translation
  • UTF-8 encoding is applied automatically for all xml files uploaded via API
  • Filter settings cannot be changed, XML tags extraction is not available (which is available in the desktop app).
  • XML files with HTML tags are not supported; HTML tags cannot be processed correctly (which is available in the desktop app).

Related Articles: Send translated files back to the system


box Generate a Text United API key

To generate your API key for integration with Text United, log in to Text United.

From the user menu, select API integration.

On the API integration page you'll have the your company ID displayed. Click on the GENERATE KEY button, which will create your API in the input field above the buttons.

Generate Api Key Step 1

Generate Api Key Step 2

box Accounts

To get the list of all users registered with your company (at Text United), call the Employees method. The result is a collection of objects describing each company employee.

URI: https://www.textunited.com/api/employees
Http method: GET
URL parameters: none

Returns:

Collection of Employee objects. Each object has the following properties:

Property Description
Id System ID of the user.
Email Email address(email address is also the login for that user).
FirstName User's first name.
LastName User's last name.
Phone Phone number (optional).
Position Position in the company (optional).

Example


Example


box Create a User

Users can be created by calling the account method that accepts a JSON object describing the user. The newly-created users are sent an email with a confirmation link - they must click and follow it in order to set the password.

URI: https://www.textunited.com/api/account
Http method: POST
URL parameters: none

Input object:

Property Description
Email Email address(email address is also the login for that user).
FirstName User's first name.
LastName User's last name.
Phone Phone number (optional).

Example


box List of projects

To get the list of all on-going projects of the company, call the Projects method.

URI: https://www.textunited.com/api/projects
Http method: GET
URL parameters: none


Example


C# Example


Returns:

Collection of Project objects. Properties of each project are described below.

Property Description
Id System ID of the project.
Name Name of the project.
Description Additional information about the project.
CreationDateUtc Date of creation (UTC time).
SourceLanguageId ID of the source language (see Languages for more information about languages).
TargetLanguageId ID of the target language (see Languages for more information about languages).
SourceLanguageCode Two-letter code of the source language.
TargetLanguageCode Two-letter code of the target language.
StartDateUtc Date when the project starts (UTC time).
EndDateUtc Date when the project ends (UTC time).
State Current state of the project. Possible values are "In preparation", "In progress", "Completed", "Enquiry", "All", "Undefined", "Archiving", "InArchive", "Holding", "On Hold", "System Processing", "System Processing Error" .
OwnerId ID of the user who created/owns the project.
OwnerName Name of the user who created/owns the project.
ManagerId ID of the user who is responsible for managing the project.
ManagerName Name of the user who is responsible for managing the project.
Progress Overall progress of the project.
TranslationProgress Progress of the translation task
ProofreadingProgress Progress of the proofreading task
ReferenceNumber Additional information about the project reference number.

box Project details

To get detailed information about a project, call the Projects method with the project ID specified in URI. The result includes all general properties of the project, as well as the detailed analysis of the text being translated, project team and collections of translation memories and repositories linked to the project.

URI: https://www.textunited.com/api/projects/{ID}
Http method: GET
URL parameters: none

Returns:

Collection of Project objects. Properties of each project are described below.

Property Description
Id System ID of the project.
Name Name of the project.
Description Additional information about the project.
CreationDateUtc Date of creation (UTC time).
SourceLanguageId ID of the source language (see Languages for more information about languages).
TargetLanguageId ID of the target language (see Languages for more information about languages).
SourceLanguageCode Two-letter code of the source language.
TargetLanguageCode Two-letter code of the target language.
StartDateUtc Date when the project starts (UTC time).
EndDateUtc Date when the project ends (UTC time).
State Current state of the project. Possible values are "In preparation", "In progress", "Completed".
OwnerId ID of the user who created/owns the project.
OwnerName Name of the user who created/owns the project.
ManagerId ID of the user who is responsible for managing the project.
ManagerName Name of the user who is responsible for managing the project.
ManagerPhone Phone number of the project manager.
ManagerEmail Email address of the project manager.
ReferenceNumber Additional information about the project reference number.
LockContextMatches Boolean value indicating whether context matches are locked or not.
Lock100Matches Boolean value indicating whether 100% matches are locked or not.
Progress Overall progress of the project.
TranslationProgress Progress of the translation task
ProofreadingProgress Progress of the proofreading task
Analysis Collection of Analysis Item objects (see below).
Team Members of the project team. ollection of TeamMember objects (see below).
TranslationMemories Translation memories linked to the project. Collection of TranslationMemory objects (see below).
TerminologyRepositories Terminology repositories linked to the project. Collection of TerminologyRepository objects (see below).
FilesCount Number of files uploaded to the project.
CustomField1 Additional information identifying the project in an external system*.
CustomField2 Additional information identifying the project in an external system*.

*see Create a managed project

AnalysisItem object:

Property Description
Range Matching range (descriptive value).
Segments Number of segments in the given matching range.
Words Number of words in the given matching range.
Characters Number of characters in the given matching range.
Phone Phone number (optional).
Percent Percentage of words from the given matching range within the total number of words in the project.

TeamMember object:

Property Description
Id System ID of the team member.
Name User's name (first name and last name combined).
Email User's email address.
Phone User's phone number.
IsTranslator Boolean value indicating whether the user has a translation role in the project or not.
IsInCountryReviewer Boolean value indicating whether the user has an in-country review role in the project or not.
TranslationRate Translation rate.
TranslationProductivity Translation productivity.
ProofreadBy ID of the proofreader assigned to the translator (in case of proofreader, the field has a null value).

TranslationMemory object:

Property Description
ID System ID of the translation memory.
Name Name of the translation memory.
Entries Number of entries.
ModificationDateUtc Date of last modification (UTC time).

TerminologyRepository object:

Property Description
ID System ID of the repository.
Name Name of the repository.
Entries Number of entries.
ModificationDateUtc Date of last modification (UTC time).

Offer:

Property Description
Id ID of the offer in the system.
Date Issue date.
Currency Currency name.
TranslationRate Rate for one word of translation.
ProofreadingRate Rate for one word of proofreading.
TranslationTotal Total amount for translation.
ProofreadingTotal Total amount for proofreading.
ProjectManagementTotal Total amount for handling the project.
AdditionalItems Other items included in the offer (a collection of names and amounts).
Total Total value of the offer.

Example


box Project files

Call the ProjectFiles method to get the list of files included in a project.

URI: https://www.textunited.com/api/projectfiles?projectId={ID}
Http method: GET
URL parameters: project

Input parameter Description
project ID of the project

Returns:

A collection of ProjectFile objects.

Property Description
File System ID of the file.
Filename Name of the file
Subdir Path to the sub-directory containing the file in the project files hierarchy.
Words Number of the words for translation.
Status Status of the file. Possible values are:
Waiting - waiting for being processed or translated;
ProcessingError - error when processing the file after upload;
NotTranslated - uploaded into the project, processed but not translated yet;
Translated - translated, ready for the download;
TranslationError - error when translating the file.

Example


box Updating files in project

When the project is in-progress state, you may upload new files or update the existing ones. In order to do this, send a POST request to:

URI: https://www.textunited.com/api/projectfiles
Http method: POST

Input parameter Description
ProjectId Project ID field
Files Collection of the file objects.

Each file must have the following properties:

Input parameter Description
Filename Content
File name string Base64-encoded content of the file.

The request is served asynchronously. That means, you’ll immediately get a boolean response indicating whether it was accepted (true – when accepted). But the process may take a while. You’ll see the change in the project after couple of seconds or minutes, depending on the project size. Please keep in mind, that if there are any files in the update matching the files already included in the project, they will overwrite the existing ones. Any new files will be simply added to the project.

JSON Example


box Downloading translated files

To get a translated file from a project, call the ProjectFiles method specifying the project ID and the file ID to download with a type set to "translated". Translated files are generated by the system after sending a PUT request to ProjectFiles method (see Translate files). Before downloading the translation, first check if the file had already been translated. You can get that information by reading the collection of all project files and looking for "translated" status.

URI: https://www.textunited.com/api/projectfiles?projectId={ID}&fileId={File}&type=translated
Http method: GET
URL parameters: project, file

Input parameter Description
project ID of the project.
file ID of the file to download.

Returns:

An object of a file with the properties listed below.

Property Description
File System ID of the file.
Filename Name of the file
Subdir Path to the sub-directory containing the file in the project files hierarchy.
FileSize Size of the file in bytes
Content Content of the file encoded in base64 string.

Example


box Download source file

To get the source file from a project, call the ProjectFiles method specifying project ID and the file ID to download. Source file is the original version of the file uploaded for translation.

URI: https://www.textunited.com/api/projectfiles?projectId={ID}&fileId={FileID}&type=source
Http method: GET
URL parameters: project, file

Input parameter Description
project ID of the project.
file ID of the file to download.

Returns:

An object of a file with the properties listed below.

Property Description
File System ID of the file.
Filename Name of the file
Subdir Path to the sub-directory containing the file in the project files hierarchy.
FileSize Size of the file in bytes
Content Content of the file encoded in base64 string.

Example


boxRequest translation of files

To request the translation of the files in the project you need to send PUT request to ProjectFiles resource(controller) and provide it project’s ID as a parameter. This will start the process of translation for all files in this project. You can check whether files are translated and ready for download by requesting project files collection (see Project files) and looking for Translated status of a file. See Project files for the complete list of file statuses.

URI: https://www.textunited.com/api/projectfiles?projectId={ID}
Http method: PUT
URL parameters: project

Input parameter Description
project ID of the project.

Returns:

Boolean value indicating whether the translation process has been started.


box Create a project

Creating a project is a simplified method of creating a regular translation project but limited to one translator, one proofreader and one in-country reviewer. By calling this method you can set-up and kick-off the project in one turn. An immediate result of the call is an ID of newly created project. Than the project undergoes a kick-off procedure that can take some time (usually no more than one minute, but these could be few minutes as well). After the kick-off is finished the project is moved to In-Progress state and the packages are assigned to translator, proofreader and in-country reviewer. If for any reasons project cannot be kicked off, it stays in In-Preparation state and can be opened in Text United App.

Document files have to be passed as a collection of UploadFile objects (even if there’s only one document to upload). Each element of the collection consists of two fields – file name (may include a relative path to the file in the project file hierarchy) and file content. Extension of the name determines a filter that is going to be used. For example files that ends with ".txt" will be processed using Unicode Text filter, files which names end with ".docx" will be processed as MS Word documents, and so on. Content of the file has to be encoded as base64 string.

URI: https://www.textunited.com/api/fastproject
Http method: POST
URL parameters: none
Returns: Project ID

JSON input object:

Input parameter Description
ProjectName Name of the project.
SourceLanguageId ID of the source language of the project.
TargetLanguageId ID of the target language of the project.
Description Additional information attached to the project.
EndDate Project's deadline.
Files Collection of files for translation. Each element of hte collection is an object of UploadFile.
TranslatorId ID of translator's account. See Accounts method for collection of company's accounts.
ProofreaderId ID of a proofreader's account. May be null if no proofreading is needed. See Accounts method for collection of company's accounts.
InCountryReviewerId ID of in-country reviewer.May be null if no in-country review is needed. See Accounts method for collection of company's accounts.
ReferenceNumber Project's reference number.
MachineTranslation Setting it to true enables the Machine Translation that will pre-translate the project.

UploadFile object:

Property Description
Filename Name of file. May include relative path in the project files hierarchy.
Content Content of a file encoded as base64 string.

Example


box Create a managed project

A ManagedProject method creates a regular translation project that is sent to Text United for further handling. Text United is responsible for set-up, translation and delivery of files.

URI: https://www.textunited.com/api/managedproject
Http method: POST
URL parameters: none
Returns: Project ID

JSON input object:

Input parameter Description
ProjectName Name of the project.
SourceLanguageId ID of the source language of the project.
TargetLanguageId ID of the target language of the project.
Description Additional information attached to the project.
EndDate Project's deadline.
Files Collection of files for translation. Each element of hte collection is an object of UploadFile.
ReferenceNumber Project's reference number.

Send translated files back to the system

If PostBackUrl is set to a non-null value, the project files will be automatically sent back to the given URL as a POST request. Keys for the data included are as follows:

project - ID of the project.
file - ID of the translated file.
filename - Name of the translated file.
content - File content encoded as Base64 string.

Property Description
PostBackUrl Optional. URL used to post back translated files (e.g. http://www.company.com/translation-collector).
CustomField1 Optional. Additional information identifying the project in an external system. Use it to save any string value with the project.
CustomField2 Optional. Additional information identifying the project in an external system. Use it to save any string value with the project.

UploadFile object:

Property Description
Filename Name of file. May include relative path in the project files hierarchy.
Content Content of a file encoded as base64 string.

IMPORTANT : Project end date may not be earlier than project creation date.


Example


box Terminology search

Requesting the TerminologySearch resource is a way to search for a given phrase in all company terminology repositories and glossary packages.

URI: https://www.textunited.com/api/TerminologySearch?phrase={search_phrase}& language={language_id}
Http method: GET
URL parameters: phrase, language

URL parameters:

Input parameter Description
phrase Phrase to search for.
language Language of the serch phrase. May be left empty, if you want to search for a given phrase in all languages. If it's not null, the language value must be an ID of the language, as returned by Languages resource.

Result of the search is an object that contains two collections: Concepts and GlossaryItems. Every item in the Concepts collection is a concept in a terminology repository (i.e. wrapper for terms of the same meaning in different languages). On the other hand, every element of the GlossaryItems collection is an entry in a glossary package that is a part of an in-progress project.

Example of the result set

Concept object

A concept object represents a group of terms of the same meaning in different languages. For example, the concept “car" can include the terms “car” in English, “auto” in German and “voiture” in French. Each concept has a collection of terms and some other attributes that describe the concept itself.

Property Description
Terms Collection of Term objects that compose the concept.
TerminologyRepositoryId ID of the repository that the concepts come from.
TerminologyRepositoryName Name of the repository that the concepts come from.
Rank Match level of the concept(relevance of the concept returned by the search method).
Id ID of the concept.
Description Additional text describing the concept.

Glossary item object

A GlossaryItem object represents one entry in a glossary package.

Property Description
Project ID of the project that a glossary item belongs to.
ProjectName Name of the project that a glossary item belongs to.
Rank Match level of the term (relevance of the term).
SourceText Text of the source.
TargetText Translation of the source text.
ModifiedUtc Time of the last modification of the item.
ModifierName Name of the user who saved the last version of the translation.
ReviewedUtc Time when the term was reviewed.
ReviewerName Name of the user who reviewed the translation.

Term object

A term object represents one element in the Terms collection of a Concept.

Property Description
Rank Match level of the term (relevance of the term).
Id ID of the term.
ConceptId ID of the concept that the term belongs to.
Text Text of the term.
Language ID of the term's language.
LanguageCode Code of the term's language (e.g. "EN-GB").
DefaultTerm Boolean value indicating if the term is a preferred translation of the concept in the given language or not.
CreateUtc UTC time of creating the term.
CreatorName Name of the user who created the term.
ModifiedUtc UTC time of the last modification of the term.
ModifierName Name of the user who modified the term.
ReviewedUtc UTC time of when the term was checked by a reviewer.
ReviewerName Name of the user who reviewed the term.
AcceptedByReviewer Boolean value indicating if the term has been checked and accepted by reviewer or not.
Usage Additional information about the usage of a term.
Notes Additional information for the term.
Context Additional information about the contexts in which the term is used.
Abbreviation Abbreviation of the term.
Prohibited Boolean value indicating if the given version of term should not or should be used.


box Sending translated files back to your system

If PostBackUrl is set to a non-null value, the project files will be automatically sent back to the given URL as a POST request. Keys for the data included are as follows:

project - ID of the project.
file - ID of the translated file.
filename - Name of the translated file.
content - File content encoded as Base64 string.

JSON input object:

Property Description
PostBackUrl Optional. URL used to post back translated files (e.g. http://www.company.com/translation-collector).

box Languages

To get the list of all available languages call the Languages method.

URI: https://www.textunited.com/api/languages
Http method: GET
URL parameters: none

Returns:

A collection of SystemLanguage objects.

Property Description
Id ID of the language.
SystemName System Name of the language.
NativeName Language Names in Native Language.
LangCode Codes for the Representation of Names of Languages.
DescriptiveName Descriptive Name of Languages.
IsRtl Indicates if the language has a right-to-left writing system.

Example of the result set


box Concordance Search

Concordance searching enables you to search the translation memory for a particular word or phrase. The list of the system languages you can see above at the "Languages" section.

URI: https://www.textunited.com/api/ConcordanceSearch?searchPhrase={searchPhrase}&sourceLanguage={sourceLanguage}&targetLanguage={targetLanguage}
Http method: GET
URL parameters: searchPhrase, sourceLanguage, targetLanguage

URL parameters:

Input parameter Description
searchPhrase Phrase or word to search for.
sourceLanguage Language of the serched phrase.
targetLanguage Target language for the searched phrase.

Returns:

A collection of ConcordanceSearch objects.

Property Description
SourceText The word or phrase that was used as a parameter for search in the translation memory.
TargetText The word or phrase from translation memory that matches the search parameter.
Rank Rank of the searched result.
DatabaseType Type of the translation database where the search was performed.
Possible results:
ProjectTM,
ProjectGlossary,
TranslationMemory,
TerminologyRepository
DatabaseName Name of the database.

Example of the result set

C# example


box Machine Translation

Machine translation it's a group of methods allowing you to translate the languages from one to another. The list of available languages you can find at Languages section. After sending the data via the Machine Translation POST method you will get the string with a token that you can use to check the current status of translating data or you can use it to get already translated text.

  • Use MachineTranslation POST method to send the text that you want to translate.
  • URI: https://www.textunited.com/api/MachineTranslation
    Http method: POST
    Returns: token


  • Use MachineTranslationStatus GET method to get the status of the posted file.
  • URI: https://www.textunited.com/api/MachineTranslationStatus?token={yourToken}
    Http method: GET
    URL parameters: token


  • Use MachineTranslation GET method to get the translated text.
  • URI: https://www.textunited.com/api/MachineTranslationStatus?token={yourToken}
    Http method: GET
    URL parameters: token

MachineTranslation POST

JSON input object:
Input parameter Description
FileName File's name that you sent for the translation.
FileContent The text of the file represented as a 64base string.
SourceLanguageId The ID of the language from which the translation should be done.
TargetLanguageId The ID of the language to which the text should be translated on.
Example of the JSON input object:

C# example

MachineTranslationStatus GET

Returns of the PublicFileStatus object:
Property Description
FileName The word or phrase that was used as a parameter for search in the translation memory.
Status The word or phrase from translation memory that matches the search parameter.
Possible results:
Undefined
Waiting
Processing
OK
Error
Quota Exceeded
Filter Filter object. Contains Id and the name of the filter that was used to the sent text.
Size Size of the translated text.
Words The number of the words.

Example of the object:

C# example

MachineTranslation GET

Returns:

Translated text represented as a base64 string.

C# example