|
University Research Program for Google Translate |
|
Google Research Other Google Resources |
DocumentationThe University Research Program for Google Translate provides researchers, in the field of automatic machine translation, tools to help compare and contrast with, and build on top of, Google's statistical machine translation system. The research program provides a programmatic interface (API) allowing researchers to submit text for translation, and then receive back detailed results of that translation, including many hypothesis translations or word alignment information. Detailed translations can be very useful to the research community in providing the ability to do detailed comparison of Google's system with other research systems as well as providing a platform on which other researchers can build. The program currently supports translations between the following language pairs:
Also note that in order to provide a reliable service, for each approved application, researchers may use this service for 2 years. After that period, researchers are certainly welcome to reapply. Contents
Quick start with the client libraryFor those who are anxious to get started, use this quick start guide. For a better understanding in how the research API works, continue reading the rest of the guide.
AudienceThis document is intended for researchers participating in the University Research Program for Google Translate. Researchers in this program may use the research API described to write client applications that can interact with Google Translate. Each example in this document first describes how the HTTP-level protocol works when requesting translations, then shows how to use the Java client library to issue those requests. If your client is written in another language, it is possible to use the HTTP-level protocol with any language that can handle HTTP requests and responses, but it may be more complicated to do so. For that reason, we highly recommend using the provided client library. Terms of useYou agree to abide by the University Research Program for Google Translate Terms of Use when using the Google Translate Research API. Interacting with Translate: examplesTranslation requests are issued as a query (with a GET request) and the response is returned as an XML feed with either a single entry containing the translation (simple translations) or multiple entries containing each hypothesis translation (detailed translations). This section will show you how to issue these queries and access the results, using either the HTTP-level protocol or the Google data API client library. Using the Translate Research API: Create a Translation accountBefore you can access the Translate Research API you must create an account and request access to the Translate Research API for your account. Access to the research API is only granted to participants in the University Research Program for Google Translate. To participate in this program, please submit a proposal. AuthenticationThe Translate Research API uses Google Account Authentication to authenticate users and allow access to the research API only to approved participants in the University Research Program for Google Translate. It is important to remember to keep your Google account secure when using the research API.
You can authenticate using the HTTP-level protocol or using the client library. The client library is highly recommended as it simplifies all aspects of using the research API. To authenticate at the protocol level, send a POST to the following URL: https://www.google.com/accounts/ClientLogin The
If the authentication request fails, you'll receive an HTTP If it succeeds, then the response from the service is an HTTP Here is an example using curl -d "Email=username@domain&Passwd=password&service=rs2" https://www.google.com/accounts/ClientLogin Make sure you remember to substitute in your
Authentication using the client libraryUsing the java client library, authentication is as simple as defining a TranslationService and adding your user credentials to that service.
// Create a TranslationService and include information about your
// application, "companyName-applicationName-versionID"
TranslationService service = new TranslationService("exampleCo-exampleApp-1");
// Create reader to get login info from user
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
// Get login information
System.out.print("Login: ");
String login = br.readLine();
System.out.print("Password: ");
String password = br.readLine();
// specify the user credentials requesting access
service.setUserCredentials(login, password);
When Simple TranslationsSimple translations can be requested, which will provide you Google's best translation of your request text. You may issue simple translation requests using either the HTTP-level protocol or using the client library. Using the HTTP-level protocol, simple translation requests are performed by sending a HTTP GET request to the following URL: http://translate.google.com/researchapi/translate The
In addition to the standard query parameters to the GET request, authentication information must also be provided. Authentication information must be provided in the HTTP-header as follows: Authorization: GoogleLogin auth=AUTH_TOKEN where AUTH_TOKEN is a 160 character string returned from the ClientLogin URL as the Auth value, described above. An example using curl -H "Authorization: GoogleLogin auth=yourAuthToken" "http://translate.google.com/researchapi/translate?sl=en&tl=ar&q=This+is+a+test." where Following a successful translation, the research API will return an HTTP
<feed>
<id>http://translate.google.com/researchapi/translate</id>
<updated>2006-08-31T17:32:11.434Z</updated>
<title type="text">Translation Feed</title>
<gt:translation lang="en">This is a test</gt:translation>
<entry>
<id>http://translate.google.com/researchapi/translate/do_not_use</id>
<updated>2006-08-31T17:32:12.615Z</updated>
<title type="text">Translation</title>
<gt:translation lang="ar">هذا هو الاختبار</gt:translation>
</entry>
</feed>
Shown above, we can see the If your request fails for some reason, the research API may return a different status code; for information about the status codes, see the Protocol document - HTTP status codes. Simple Translations using the client libraryUsing the java client library, you can easily issue queries and process the response without having to deal with HTTP requests and XML parsing. First, you must specify the appropriate URL to which you'll issue the queries, create a TranslationService and specify your user credentials (as described above), and specify the type of feed the service will return:
// Create a TranslationService and include information about your application,
// "companyName-applicationName-versionID"
TranslationService service = new TranslationService("exampleCo-exampleApp-1");
// Create reader to get login info from user
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
// Get login information
System.out.print("Login: ");
String login = br.readLine();
System.out.print("Password: ");
String password = br.readLine();
// specify the user credentials requesting access
service.setUserCredentials(login, password);
Once you've prepared the TranslationService, you can create a query and send that query to the service, retrieving a resulting feed containing one entry, with your translated text.
// Create a query with appropriate parameters
TranslateQuery query = new TranslateQuery("This is a test", "en", "ar");
// Send the query to the translation service, retrieving the resulting feed
TranslateFeed feed = service.query(query, TranslateFeed.class);
Now that the TranslateFeed has been retrieved for your translation request, verify it has at least one TranslateEntry, get that entry, and display relevant information from the entry.
// As long as there's at least one entry
if (feed.getEntries().size() > 0) {
// Get the entry
TranslateEntry entry = feed.getEntries().get(0);
// Display the translated string with other information
System.out.println("Feed title: " + feed.getTitle().getPlainText());
System.out.println("Feed updated: " + feed.getUpdated());
System.out.println("Entry title : " + entry.getTitle().getPlainText());
System.out.println("Entry updated: " + entry.getUpdated());
System.out.println("Translated Text: " + entry.getText() + "\n\n");
}
This code is included with the client toolkit as the
Detailed TranslationsTwo types of detailed translations can be requested. The first of which will provide you with a list of hypothesis translations of your requested text. This N-best list of hypotheses will include the total cost of each hypothesis, as well as the cost of each feature that makes up that total cost. The list will be ordered from best to worst hypothesis (lowest to highest cost). The second type of detailed translation is to request alignment information. Alignment responses include information on which words in the resulting translation align to which words in the original text. You may issue detailed translation requests using either the HTTP-level protocol or using the client library. Using the HTTP-level protocol, detailed translation requests are performed by sending a HTTP GET request to the same URL as mentioned above: http://translate.google.com/researchapi/translate The
The first three parameters are always required. Using either of the last two parameters constitutes a detailed translation request, either for a list of hypotheses or for alignment information, depending on which parameter is included. Again, in addition to the standard query parameters to the GET request, authentication information must also be provided. Authentication information must be provided in the HTTP-header as follows: Authorization: GoogleLogin auth=AUTH_TOKEN where AUTH_TOKEN is a 160 character string returned from the ClientLogin URL as the Auth value, described above. An example using curl -H "Authorization: GoogleLogin auth=yourAuthToken" "http://translate.google.com/researchapi/translate?sl=en&tl=ar&q=This+is+a+test.&nbest=5&align=1" where Following a successful translation, the research API will return an HTTP
Detailed N-best RequestsAn example response for a detailed N-best translation might look something like this:
<feed>
<id>http://translate.google.com/researchapi/translate</id>
<updated>2006-09-05T23:59:37.924Z</updated>
<title type="text">Translation Feed</title>
<gt:translation lang="en">This is a test.</gt:translation>
<entry>
<id>http://translate.google.com/researchapi/translate/do_not_use</id>
<updated>2006-09-05T23:59:41.500Z</updated>
<title type="text">Translation</title>
<gt:translation lang="ar">هذا هو المحك.</gt:translation>
<gt:feature id="TOTAL" score="1.345591"/>
</entry>
... snip ...
<entry>
<id>http://translate.google.com/researchapi/translate/do_not_use</id>
<updated>2006-09-06T00:27:24.269Z</updated>
<title type="text">Translation</title>
<gt:translation lang="ar">وهذا الاختبار.</gt:translation>
<gt:feature id="TOTAL" score="1.521322"/>
</entry>
</feed>
Shown above, we can see the If your request fails for some reason, the research API may return a different status code; for information about the status codes, see the Protocol document - HTTP status codes. Detailed Alignment RequestsAn example response for a detailed alignment translation might look something like this:
<feed>
<id>http://translate.google.com/researchapi/translate</id>
<updated>2006-09-05T23:59:37.924Z</updated>
<title type="text">Translation Feed</title>
<gt:translation lang="en">This is a test.</gt:translation>
<entry>
<id>http://translate.google.com/researchapi/translate/do_not_use</id>
<updated>2006-09-05T23:59:41.500Z</updated>
<title type="text">Translation</title>
<gt:translation lang="ar">هذا هو الاختبار.</gt:translation>
<gt:alignment word="هذا" position="0"/>
<gt:alignment word="هو" position="5"/>
<gt:alignment word="اختبار." position="8"/>
<gt:alignment word="اختبار." position="10"/>
</entry>
</feed>
Shown above, we can see the If your request fails for some reason, the research API may return a different status code; for information about the status codes, see the Protocol document - HTTP status codes. Detailed Translations using the client libraryUsing the java client library, you can easily issue queries and process the response without having to deal with HTTP requests and XML parsing. First, you must specify the appropriate URL to which you'll issue the queries, create a TranslationService and specify your user credentials (as described above), and specify the type of feed the service will return:
// Create a TranslationService and include information about your application,
// "companyName-applicationName-versionID"
TranslationService service = new TranslationService("exampleCo-exampleApp-1");
// Create reader to get login info from user
BufferedReader br = new BufferedReader(new InputStreamReader(System.in));
// Get login information
System.out.print("Login: ");
String login = br.readLine();
System.out.print("Password: ");
String password = br.readLine();
// specify the user credentials requesting access
service.setUserCredentials(login, password);
Once you've prepared the TranslationService and the URL, you can build a query:
// Create a query with appropriate parameters
TranslateQuery query = new TranslateQuery("This is a test", "en", "ar");
Depending on whether you want many hypothesis translations or alignment information use on of the following:
// request 10 hypothesis translations
query.setDetailedRequest("10");
or // request alignment information query.setAlignmentRequest(); Then, send that query to the service: // Send the query to the translation service, retrieving the resulting feed TranslateFeed feed = service.query(query, TranslateFeed.class); The resulting feed will contain either many entries, one for each hypothesis translation, or a single translation with alignment information. Now that the TranslateFeed has been retrieved for your translation request, either loop through each entry and display the relevant information for each translation hypothesis.
// For each entry
for (int i=0; i<feed.getEntries().size(); i++) {
// Get the entry
TranslateEntry entry = feed.getEntries().get(i);
// Display the translated string with other information
System.out.println("\nEntry title : " + entry.getTitle().getPlainText());
System.out.println("Entry updated: " + entry.getUpdated());
System.out.println("N-best Translated Text: " + entry.getText());
// Display the scoring features
System.out.print("Scoring features: ");
for (ScoringFeature feature : entry.getScoringFeatures()) {
System.out.print(feature.getID() + "=" + feature.getScore() + " ");
}
System.out.print("\n");
}
or display the alignment information:
// Get entry
TranslateEntry entry = feed.getEntries().get(0);
// Display alignment information
System.out.print("Alignments: ");
for (TranslationAlignment alignment : entry.getTranslationAlignments()) {
System.out.print(alignment.getWord() + " (" + alignment.getPosition() + ") ");
}
System.out.print("\n");
This code is included with the client toolkit as the
Downloading and using the client libraryThe Google Translate Research API client library is currently for Java only and depends on the GData java client library. To use the library you will have to download four packages. To use the client library, 1.) download the Google Translate Research API java client library here. Extract the zip file. By default, the zip extracts to directory
Since this client library depends on the GData java client library you must 2.) download the GData java client library here. The GData library also depends on JavaMail and JavaBeans Activation Framework (jaf), so you'll need to 3.) Download the JavaMail API and 4.) Download the JavaBeans Activation Framework Extract all of the libraries into the same directory: unzip translate_api_java.zip unzip gdata.java-1.12.0.zip unzip javamail-1_4.zip unzip jaf-1_1-fr.zip Then, go in to the cd translate_api Then to build the example clients, use the following (from within the
javac *.java -classpath ../gdata/java/lib/gdata-client-1.0.jar:lib/translate-1.0.jar:. And then to run those example clients, use the following (from within the
java -classpath ../jaf-1.1/activation.jar:../javamail-1.4/mail.jar:../gdata/java/lib/gdata-client-1.0.jar:lib/translate-1.0.jar:. \
SimpleClient en ar "This is a test."
java -classpath ../jaf-1.1/activation.jar:../javamail-1.4/mail.jar:../gdata/java/lib/gdata-client-1.0.jar:lib/translate-1.0.jar:. \
DetailedClient en ar 10 "This is a test."
These example clients will ask you for your |