TPX: Translator Profile eXchange 0.16

This version: http://www.proz.com/tpxsoa/doc/tpx/version/0.16
Latest version: http://www.proz.com/tpxsoa/doc/tpx

Editor: Jason Grimes <jg@proz.com>

Copyright © 2004-2019 ProZ.com. All rights reserved.


Abstract

This document describes the Translator Profile eXchange format (TPX). TPX is a proposed standard for the exchange of profile data for translators and interpreters. The current version of TPX is an early draft being evaluated and improved by the TPX working group.

Status of this document

This document is a working draft, and may be updated, replaced, or made obsolete by other documents at any time.

Table of Contents

1. Introduction
1.1. What is TPX?
1.2. The Benefits of TPX
2. APIs
2.1 Introduction
2.2 TPX web service URL
2.3 HTTP response codes
2.4 Errors
2.5 Profile API
2.5.1 profile/details method
2.5.2 profile/search method
2.5.3 profile/sendmsg method
2.6 Data API
2.6.1 data/list-languages method
2.6.2 data/list-subject-areas method
2.6.3 data/list-services method
2.7 PHP client library
3. TPX format
2.1. Standards Compliance
2.2. Character Encoding
2.3. Markup formats: JSON or XML
2.4. Data structure

Appendices

A. Sample JSON data structure
B. Sample XML data structure
C. Sample JSON data/list-languages response
D. Sample JSON data/list-subject-areas response
E. Glossary
F. References

1. Introduction

1.1. What is TPX?

The Translator Profile eXchange format (TPX) is a proposed standard for the exchange of profile data for translators and interpreters.

In practice, translators will be able to create TPX resumes/CVs and send these to language service providers (LSPs) in lieu of, or in addition to, their regular resumes/CVs.

The proposed standard contains a unique TPX identifier that will make it possible to obtain up-to-date profile data from TPX-registered translators from time to time, in a standardized or even automated manner. It will make sense for information such as availability to be updated regularly in one place by a translator, and then passed automatically using TPX standard tagging to all interested clients.

The current version of TPX is an early draft being evaluated and improved by the TPX working group.

1.2. The Benefits of TPX

By providing a standardized way of presenting the services, skills, experience, rates and other information in a translator's profile or CV, TPX will make the process of locating and qualifying language professionals more efficient for LSPs. It will also make the process of marketing oneself, and keeping information such as availability up to date among existing clients, easier for language professionals.

TPX will make it possible for LSPs to request and share translator data in a standardized way. This will enable companies to effectively connect their vendor management systems together, transferring vendor data from one system to another using automated tools.

Because of the standardized format, it will be possible for LSPs to process applications more efficiently than they can now. Automated tools will be able to extract, display and search whatever data is of particular interest or need to a given company. A peripheral benefit of having a standard set of fields is that completeness of data will be encouraged.

One possible application in which the TPX standard would be useful is in checking on the current availability of known translators. Many translators maintain their availability data at ProZ.com now, but can not be expected to maintain availability data with all the customers for whom they work. A TPX standard will define a way for LSPs to query ProZ.com's servers to check the availability of known translators when new projects arise.

Another possible application in which TPX would be useful is from within desktop tools such as project management software. A project manager working from within one of these tools could ask for a list of translators working in a certain pair and field. The software could query ProZ.com's servers for a list of appropriate professionals.

2. APIs

2.1 Introduction

ProZ.com provides TPX service APIs which allow authorized parties to find translators and retrieve their profile information in TPX format (in accordance with the profile owners' privacy preferences).

To use the API, you must first sign up for an API key. Please contact ProZ.com for information about how to do this.

Users will be limited to a reasonable number of API requests per day (this limit has not yet been determined).

2.2 TPX web service URL

The TPX service can be accessed via simple REST-style HTTP requests.

All TPX service APIs are accessed at URLs in the following format: http://www.proz.com/tpxsoa/{api}/{method}?{parameters}

Parameters common to all TPX APIs:

2.3 HTTP response codes

Each request will return an HTTP Response code to indicate the status of the request, in addition to any data that it returns.

2.4 Errors

When errors can be determined, the results you receive will contain a structure with type = error. After receiving the request, you should first check the HTTP status code. Anything other than 200 OK indicates that an error could be present and should be acted upon.

Example:

{
  "type": "error",
  "msg": "The requested user could not be found"
}

2.5 Profile API

2.5.1 Details method

Retrieve the details for a given profile.

URL: profile/details

HTTP Method(s): GET

Parameters (in addition to the common API parameters):

Example URL: http://www.proz.com/tpxsoa/profile/details?uuid=67384b02-6279-4ace-ac8c-4ce6b5291f27&format=json&api_key={your-api-key}

See below for a sample JSON response.

2.5.2 Search method

URL: profile/search

HTTP Method(s): GET

Example URL: http://www.proz.com/tpxsoa/profile/search?format=json&api_key={your-api-key}&word_minrate=0.2&specific_subject_areas=60,62&language_pairs=fin_eng,fin_fra

Parameters (in addition to the common API parameters):

Sorting

The search results returned from this API method will be sorted based on a custom algorithm that takes into account any certifications that each translator has undertaken, as well as positive or negative feedback from previous translation projects. This algorithm is optimized regularly to ensure that we return the best quality results.

The response will be an array of TPX profile structures. The format of each profile entry is identical to the one returned by the profile/details method.

2.5.3 Sendmsg method

URL: profile/sendmsg

HTTP Method(s): POST

Example URL: http://www.proz.com/tpxsoa/profile/sendmsg?format=json&api_key={your-api-key}

POST body:

uuids=67384b02-6279-4ace-ac8c-4ce6b5291f27,84469b91-660d-4486-af72-f76afe65bdf6&sender_name=Bob&sender_email=bob@example.org&subject=Hello+there!&body=I+need+a+translator+asap

Parameters (in addition to the common API parameters):

Example response:

{
  "results": [
    {
      "uuid": "invalid-uuid",
      "success": 0,
      "status": "error",
      "msg": "No profile was found with that UUID."
    },
    {
      "uuid": "67384b02-6279-4ace-ac8c-4ce6b5291f27",
      "success": 1,
      "status": "sent",
      "msg": "Message sent."
    },
    {
      "uuid": "84469b91-660d-4486-af72-f76afe65bdf6",
      "success": 1,
      "status": "queued",
      "msg": "Message processed for staff review."
    },
    {
      "uuid": "32a9a4d0-cb6e-463f-a0ab-63d0a0418bc7",
      "success": 1,
      "status": "sent",
      "msg": "Message sent."
    }
  ]
}

2.6 Data API

Lookup the possible values for the data points that can be queried through this system.

2.6.1 List languages method

URL: data/list-languages

HTTP Method(s): GET

Example URL: http://www.proz.com/tpxsoa/data/list-languages?format=json&api_key={your-api-key}

See below for a sample JSON response.

2.6.2 List subject areas method

URL: data/list-subject-areas

HTTP Method(s): GET

Example URL: http://www.proz.com/tpxsoa/data/list-subject-areas?format=json&api_key={your-api-key}

See below for a sample JSON response.

2.6.3 List services method

URL: data/list-services

HTTP Method(s): GET

Example URL: http://www.proz.com/tpxsoa/data/list-services?format=json&api_key={your-api-key}

Sample response:


[
  {
    "id":1,
    "name":"Translation"
  },
  {
    "id":2,
    "name":"Interpreting"
  },
  {
    "id":3,
    "name":"Editing\/proofreading"
  },
  {
    "id":4,
    "name":"Website localization"
  },
  {
    "id":5,
    "name":"Software localization"
  },
  {
    "id":6,
    "name":"Voiceover (dubbing)"
  },
  {
    "id":7,
    "name":"Subtitling"
  },
  {
    "id":14,
    "name":"Post-editing"
  },
  {
    "id":15,
    "name":"Transcription"
  },
  {
    "id":8,
    "name":"Training"
  },
  {
    "id":9,
    "name":"Desktop publishing"
  },
  {
    "id":10,
    "name":"Project management"
  },
  {
    "id":11,
    "name":"Vendor management"
  },
  {
    "id":12,
    "name":"Sales"
  },
  {
    "id":13,
    "name":"Operations management"
  }
]

2.7 PHP client library

A PHP client library is available to interact with the TPX service. The library consists of a collection of classes that act as a easy to use wrapper on top of the actual service. The library was created to work with a recent installation of Zend Framework.

It consists of two PHP classes that acts as easy to use wrappers on top of the HTTP-based service, and a few exception classes used internally to flag invalid requests and other error conditions. Usage example:

<?php
$api_key = '{your-api-key}';
$tpxid = '67384b02-6279-4ace-ac8c-4ce6b5291f27';
try {
  $client = Proz_Service_Client::factory(Proz_Service_Client::CLIENT_TYPE_JSON, $api_key);
  $results = $client->getDetails($tpxid);
} catch (Exception $e) {
  // process the exception here...
}

The PHP client library is available for download. This is alpha software that is being made available to help the integration of third party services.

3. TPX format

3.1. Standards Compliance

TPX follows relevant standards when available. It uses various ISO standards for date/time, language codes, and country codes. See the References section for more details.

TPX files are intended to be created automatically by export routines and processed automatically by import routines.

3.2. Character Encoding

TPX data is always in Unicode, encoded as UTF-8.

3.3. Markup formats: JSON or XML

A TPX data structure may be formatted as JSON or XML. In either case, it will have the same structure and element names.

3.4. Data Structure

A TPX data structure describes the profile of a single language professional. Each TPX data structure has a tpxid, which contains a globally unique TPX identifier for that profile. It may also contain properties such as name, contact, languages, and industryspecialties, which in turn contain more detailed information.
tpxid
A unique ID for this profile.
name
firstname
The person's first name
surname
The person's last name
site_name
The person's full name, or when the user has decided to keep that information private, the account username.
profile_url
The person's profile URL
address
city
id
A code representing the city (*** to be defined)
name
The name of the city
region
id
A code representing the region (*** to be defined)
name
The name of the region
postalcode
The postal code (or "zip code")
country
The two-letter ISO-3166 country code
contact
email
Primary email address
phone
Primary phone number
url
Primary web site URL
skype
Skype username
paypal_email
Email address to use for Paypal payment
rates
A list of different rates for different language pairs (or other special circumstances). Each block of rates information has the following properties:

languagepair
source
The source language
target
The target language
minrateperword
The minimum "per source word" rate.
targetrateperword
The desired "per source word" rate.
minrateperhour
The minimum hourly rate.
targetrateperhour
The desired hourly rate.
currency
The currency code
languages
languagepair
source
The source language
target
The target language
servicesoffered
A list of services offered in this language pair. Each service has the following properties:
id
The service ID (*** to be defined)
name
The service name (ex. "Translation", "Checking/editing", etc.)
equipment
translationsoftware
A list of translation software. Each software application has the following properties:
id
The software ID (*** to be defined)
name
The name of the software application
subjectareas
A list of subject areas. Each subject area has the following properties:
id
The ID of the subject area (*** to be defined)
name
The name of the subject area
experiencelevel
The level of experience the person has in this subject area. One of "specialty", "working", or "interest"
translationexperience
yearsexperience
A number of years of experience
yearstarted
The year the person started working in the translation industry
academics
degrees
A list of translation-related degrees held. Each degree has the following properties:
level
The type of degree, ex. "BA", "MA", "PhD"
institution
The name of the institution that granted the degree

See the sample data structures below for examples.

Appendix A. Sample JSON data structure

{
	"tpxid": "67384b02-6279-4ace-ac8c-4ce6b5291f27",
	"name": {
		"firstname": "William",
		"surname": "Prude",
		"site_name": "William Prude"
	},
	"tagline": "Best translation services around!",
	"profile_url": "http://www.proz.com/profile/41429",
	"address": {
		"postalcode": "01460",
		"country": "us"
	},
	"contact": {
		"email": "WilliamTPrude@trashymail.com",
		"phone": "978-486-9704",
		"url": [
			"http://BizQuarters.com"
		]
	},
	"rates": [
		{
			"languagepair": {
				"source": "chv",
				"target": ".fs"
			},
			"minrateperword": "0.910",
			"targetrateperword": "0.930",
			"minrateperhour": "56.330",
			"targetrateperhour": "11.950",
			"currency": "usd"
		},
		{
			"languagepair": {
				"source": "cor",
				"target": "lol"
			},
			"minrateperword": "0.240",
			"targetrateperword": "0.390",
			"minrateperhour": "29.850",
			"targetrateperhour": "24.240",
			"currency": "usd"
		}
	],
	"languages": {
		"languagepair": [
			{
				"source": "chv",
				"target": ".fs",
				"servicesoffered": [
					{
						"id": 1,
						"name": "Translation"
					},
					{
						"id": 2,
						"name": "Checking/editing"
					}
				]
			},
			{
				"source": "cor",
				"target": "lol",
				"servicesoffered": [
					{
						"id": 1,
						"name": "Translation"
					},
					{
						"id": 2,
						"name": "Checking/editing"
					}
				]
			}
		]
	},
	"equipment": {
		"translationsoftware": [
			{
				"id": 1,
				"title": "Cool Gadget Ultra v1"
			},
			{
				"id": 2,
				"title": "Powerpoint"
			}
		]
	},
	"subjectareas": [
		{
			"id": 20,
			"name": "Cinema, Film, TV, Drama",
			"experiencelevel": "specialty"
		},
		{
			"id": 25,
			"name": "Computers: Systems, Networks",
			"experiencelevel": "specialty"
		},
		{
			"id": 40,
			"name": "Engineering (general)",
			"experiencelevel": "interest"
		},
		{
			"id": 48,
			"name": "Finance (general)",
			"experiencelevel": "specialty"
		},
		{
			"id": 52,
			"name": "Forestry / Wood / Timber",
			"experiencelevel": "interest"
		},
		{
			"id": 62,
			"name": "Government / Politics",
			"experiencelevel": "working"
		},
		{
			"id": 70,
			"name": "International Org/Dev/Coop",
			"experiencelevel": "interest"
		},
		{
			"id": 71,
			"name": "Internet, e-Commerce",
			"experiencelevel": "interest"
		},
		{
			"id": 77,
			"name": "Law (general)",
			"experiencelevel": "interest"
		},
		{
			"id": 89,
			"name": "Mathematics & Statistics",
			"experiencelevel": "interest"
		},
		{
			"id": 91,
			"name": "Media / Multimedia",
			"experiencelevel": "interest"
		},
		{
			"id": 92,
			"name": "Medical: Pharmaceuticals",
			"experiencelevel": "specialty"
		},
		{
			"id": 99,
			"name": "Mining & Minerals / Gems",
			"experiencelevel": "interest"
		},
		{
			"id": 122,
			"name": "Real Estate",
			"experiencelevel": "interest"
		},
		{
			"id": 136,
			"name": "Law: Taxation & Customs",
			"experiencelevel": "interest"
		},
		{
			"id": 139,
			"name": "Tourism & Travel",
			"experiencelevel": "interest"
		}
	],
	"translationexperience": {
		"yearsexperience": 48,
		"yearstarted": 1954
	}
}

Appendix B. Sample XML data structure

<?xml version="1.0"?>
<TPX>
    <profile>
        <tpxid>67384b02-6279-4ace-ac8c-4ce6b5291f27</tpxid>
        <name>
            <firstname>William</firstname>
            <surname>Prude</surname>
            <site_name>William Prude</site_name>
        </name>
        <tagline>Best translation services around!</tagline>
        <profile_url>http://www.proz.com/profile/41429</profile_url>
        <address>
            <postalcode>01460</postalcode>
            <country>us</country>
        </address>
        <contact>
            <email>WilliamTPrude@trashymail.com</email>
            <phone>978-486-9704</phone>
            <urls>
                <url>http://BizQuarters.com</url>
                <url>http://www.proz.com/profile/41429</url>
            </urls>
        </contact>
        <rates>
            <rate>
                <languagepair>
                    <source>chv</source>
                    <target>.fs</target>
                </languagepair>
                <minrateperword>0.910</minrateperword>
                <targetrateperword>0.930</targetrateperword>
                <minrateperhour>56.330</minrateperhour>
                <targetrateperhour>11.950</targetrateperhour>
                <currency>usd</currency>
            </rate>
            <rate>
                <languagepair>
                    <source>cor</source>
                    <target>lol</target>
                </languagepair>
                <minrateperword>0.240</minrateperword>
                <targetrateperword>0.390</targetrateperword>
                <minrateperhour>29.850</minrateperhour>
                <targetrateperhour>24.240</targetrateperhour>
                <currency>usd</currency>
            </rate>
        </rates>
        <languages>
            <languagepair>
                <source>chv</source>
                <target>.fs</target>
                <servicesoffered>
                    <service>
                        <id>1</id>
                        <name>Translation</name>
                    </service>
                    <service>
                        <id>2</id>
                        <name>Checking/editing</name>
                    </service>
                </servicesoffered>
            </languagepair>
            <languagepair>
                <source>cor</source>
                <target>lol</target>
                <servicesoffered>
                    <service>
                        <id>1</id>
                        <name>Translation</name>
                    </service>
                    <service>
                        <id>2</id>
                        <name>Checking/editing</name>
                    </service>
                </servicesoffered>
            </languagepair>
        </languages>
        <equipment>
            <translationsoftware>
                <application>
                    <id>1</id>
                    <title>Cool Gadget Ultra v1</title>
                </application>
                <application>
                    <id>2</id>
                    <title>Powerpoint</title>
                </application>
            </translationsoftware>
        </equipment>
        <subjectareas>
            <industry>
                <id>20</id>
                <name>Cinema, Film, TV, Drama</name>
                <experiencelevel>specialty</experiencelevel>
            </industry>
            <industry>
                <id>25</id>
                <name>Computers: Systems, Networks</name>
                <experiencelevel>specialty</experiencelevel>
            </industry>
            <industry>
                <id>40</id>
                <name>Engineering (general)</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>48</id>
                <name>Finance (general)</name>
                <experiencelevel>specialty</experiencelevel>
            </industry>
            <industry>
                <id>52</id>
                <name>Forestry / Wood / Timber</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>62</id>
                <name>Government / Politics</name>
                <experiencelevel>working</experiencelevel>
            </industry>
            <industry>
                <id>70</id>
                <name>International Org/Dev/Coop</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>71</id>
                <name>Internet, e-Commerce</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>77</id>
                <name>Law (general)</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>89</id>
                <name>Mathematics &amp; Statistics</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>91</id>
                <name>Media / Multimedia</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>92</id>
                <name>Medical: Pharmaceuticals</name>
                <experiencelevel>specialty</experiencelevel>
            </industry>
            <industry>
                <id>99</id>
                <name>Mining &amp; Minerals / Gems</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>122</id>
                <name>Real Estate</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>136</id>
                <name>Law: Taxation &amp; Customs</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
            <industry>
                <id>139</id>
                <name>Tourism &amp; Travel</name>
                <experiencelevel>interest</experiencelevel>
            </industry>
        </subjectareas>
        <translationexperience>
            <yearsexperience>48</yearsexperience>
            <yearstarted>1954</yearstarted>
        </translationexperience>
    </profile>
</TPX>

Appendix D. Sample JSON data/list-languages response

[
	{
		"code": "abk",
		"name": "Abkhazian"
	},
	{
		"code": "ace",
		"name": "Achinese"
	},
	{
		"code": "ach",
		"name": "Acoli"
	},
	{
		"code": "ada",
		"name": "Adangme"
	}
        // more here ...
]

Appendix E. Sample JSON data/list-subject-areas response

{
	"broad": [
		{
			"id": "1",
			"title": "Tech/Engineering"
		},
		{
			"id": "2",
			"title": "Art/Literary"
		},
		{
			"id": "3",
			"title": "Medical"
		}
		// more here...
	],
	"specific": [
		{
			"id": "1",
			"title": "Accounting"
		},
		{
			"id": "2",
			"title": "Advertising / Public Relations"
		},
		{
			"id": "10",
			"title": "Aerospace / Aviation / Space"
		}
		// more here...
	]
}

Appendix F. Glossary

DTD
An SGML document has an associated Document Type Definition (DTD) that specifies the rules for the structure of the document. Several industries have standardized on various DTDs for the different types of documents that they share.
SGML
SGML stands for Standard Generalized Markup Language. An ISO standard (ISO-8879) allows the definition of structured formats. SGML is not a format by itself, but a set of rules to define formats. SGML mark-up systems are defined in Document Type Definition files (DTDs).
UTC
UTC stands for Coordinated Universal Time.
XML
XML stands for Extensible Markup Language. XML is a simplified and restricted subset of SGML.

Appendix G. References

[ISO 3166]
Codes for the representation of names of countries and their subdivisions. ISO (International Organization for Standardization), Jun 2000.
[RFC 1738]
RFC 1738 Uniform Resource Locators (URL). IETF (Internet Engineering Task Force), Dec 1994.
[RFC 3066]
RFC 3066 Tags for the Identification of Languages. IETF (Internet Engineering Task Force), Jan 2001.
[XML 1.0]
Extensible Markup Language (XML) 1.0 Second Edition. W3C (World Wide Web Consortium), Oct 2000.
[ISO]
International Organization for Standardization Web site.
[ProZ.com]
ProZ.com Web site.
[W3C]
World Wide Web Consortium Web site.