Connect SDK: Java

Pre-requisites

  • Eclipse or another IDE
  • JDK 7 or 8 (Oracle or OpenJDK)
  • git
  • maven

Library Distribution

The library is distributed on Sonatype Maven Central.

  1. Add the following dependency to your pom.xml
    <dependencies>
    <!-- your other dependencies -->
      <dependency>
        <groupId>com.translations.globallink</groupId>
        <artifactId>gcc-restclient</artifactId>
        <version>${version}</version>
      </dependency>
    </dependencies>
  2. Resolve the dependency using maven central: https://oss.sonatype.org/content/repositories/releases/com/translations/globallink/gcc-restclient/

Note: you can also download our library from Nexus: https://oss.sonatype.org/#nexus-search;quick~globallink

Sample Source Code

A sample code which uses the above library is available on the git repository.

  1. Clone the sample code locally in your filesystem: git clone https://github.com/translations-com/globallink-connect-cloud-api-java
  2. Convert the project to an Eclipse project using the maven client.
  3. Navigate to the cloned directory.
  4. Execute this in the command line mvn eclipse:eclipse
  5. The output should be as displayed below:
    [INFO] ------------------------------------------------------------------------
    Building gcc-restclient 1.0.0
    [INFO] ------------------------------------------------------------------------
    [INFO]
    [INFO] >>> maven-eclipse-plugin:2.10:eclipse (default-cli) > generate-resources @ gcc-restclient >>>
    [INFO]
    [INFO] <<< maven-eclipse-plugin:2.10:eclipse (default-cli) < generate-resources @ gcc-restclient <<<
    [INFO]
    [INFO]
    [INFO] --- maven-eclipse-plugin:2.10:eclipse (default-cli) @ gcc-restclient ---
    [INFO] Using Eclipse Workspace: C:\WORKING_TEMP\03_GL_stuff
    [INFO] Adding default classpath container: org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.7
    [INFO] Wrote settings to globallink-connect-cloud-api-java\.settings\org.eclipse.jdt.core.prefs
    [INFO] Wrote Eclipse project for "gcc-restclient" to globallink-connect-cloud-api-java.
    [INFO]
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 11.405 s
    [INFO] Finished at: 2018-08-21T10:29:11+02:00
    [INFO] Final Memory: 17M/160M
    
  6. Open Eclipse into the workspace containing your integration project.
  7. Go to File > Import.
  8. Select Existing Projects into Workspace and click Next.
  9. In the new windows, select the root directory for the project by clicking Browse, and navigate to the Eclipse project that was converted using the maven client.
  10. Perform the import as needed (options will be different depending on your Eclipse configuration).

Connect SDK: .NET

Pre-requisites

  • .NET Frameworks 4.5.2 or 4.6
  • Visual Studio
  • Nuget Package Manager

Library Distribution

To download the libraries to your system and use them in your project, do the following:

  1. Open the project where you want to code the integration.
  2. Go to Tools > Nuget Package Manager > Manage Packages for this solution.
  3. In the search bar, type globallink as the search term.
  4. Select the package GlobalLink.Connect.Cloud
  5. Select the project or projects in which you want to install the library.
  6. Below, on list of packages, select the latest stable version.
  7. Click Install.

REST API - Postman Collection

We offer a Postman collection to understand the methods and verbs of GlobalLink Connect Cloud REST API.

Import collection in Postman

  1. Open postman in your desired workspace.
  2. On the top-left button menu ribbon, click Import.
  3. Use the third tab Import from Link paste https://www.getpostman.com/collections/ebc75c66781b3263c20a for the collection and click Import.
  4. Now you have a new collection called GCC REST API v2.

Working with the Collection

The collection has 6 different variables that need to be defined:

  • url - provided by Translations.com
  • username - provided by Translations.com
  • password - provided by Translations.com
  • token - secret key generated upon starting a session (if left blank, it is filled out automatically when you execute the endpoint session/start)
  • connector_key - the public key for the connector, provided by TDC
  • user-agent - descriptive name of the application integrating (e.g. %CLIENT_NAME%_%APP_NAME%_%VERSION%)

We recommend that you create an environment to set up the variable values which to use. To do so, perform the following steps:

  1. On the right top corner, click on the configuration wheel (i.e., Manage Environments).
  2. Click Add.
  3. Fill up the variables as displayed in the screenshot and click Add.
  4. Now your environment should be listed along with the rest of environments you already had, if you had any. Close this window.
  5. Select the environment by using the drop down menu on the top right corner.
  6. From the GCC REST API v2 collection, select the endpoint under Session/Session - Start and click on SEND. The token variable will get filled with the session token value on the response, needed to execute the subsequent endpoints.

You are now setup to execute any of the endpoints and inspect the request and response JSON.

Generate Sample Code using Postman

Postman can generate sample code for each endpoint listed in the collection for a variety of languages. To see the sample code:

  1. Select an endpoint.
  2. Click Code at the top right of the window.
  3. On the code window, use the drop-down menu to select the sample code flavor you want to see:

Command Line Interface

Overview

GlobalLink Connect Cloud (GCC) Command Line Interface (CLI) is a unified tool to manage your GCC services. Using one tool to download and configure, you can control multiple GCC services from the command line and automate them through scripts.

GCC CLI introduces a set of file, user, and configuration commands to perform basic operations from the command line for translation jobs to and from GCC.

How it works

The command line tools with all dependencies are packaged in globallink-gcc-cli-x.x.x.jar

Java 1.8 or greater is required for execution.

Usage

The available commands are listed below. Each command has a list of optional and required parameters. Some parameters can be specified multiple times to provide multiple values.

You can get help on the command line to see the supported functions.

java -jar globallink-gcc-cli-x.x.x.jar -h
...

For more sophisticated usage especially with larger projects, use our integrations with various build tools (Nuget and Maven).

User Operations

  • Login

    Request a session token.

    Options Description Required Multiple
    -u Username Yes  
    -p Password Yes  
    -c Connector Key Yes  
    -l GCC URL Yes  
    -li Login Yes  
    >java -jar globallink-gcc-cli-x.x.x.jar -u username -p password -l https://connect-dev.translations.com/api/v2 -c 9037813e70121ecaf3767acf8865e649 -li
    2018-07-27 15:35:52 INFO - Logged in. Session token:ogZfCx3EXWyNgm
  • Logout

    Logout of a session using the -lo (logout) switch.

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -lo logout Yes  
    >java -jar globallink-gcc-cli-x.x.x.jar -to session-token -l https://connect-dev.translations.com/api/v2 -c 9037813e70121ecaf3767acf8865e649 -lo
    2018-07-27 15:54:14 INFO  - Logout successful

Config

  • List Supported FileTypes

    Use -f (filetypes) switch to list all filetypes supported. This requires -to session token.

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -f filetypes Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1  -f
                  
    file_type: XML
    file_type: xml
    file_type: DOC
    file_type: doc
    file_type: docx
    file_type: DOCX
              
  • List all supported source and target locales

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -e locales Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -e
    en-US English true
    de-DE German false
    fr-FR French false

Jobs

  • List of all jobs in your account, for a connector

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -b jobs list Yes  
    -st job status No Yes
    -pn page number to request No  
    -ps page size to request No  
    -t Target locale for job No Yes
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -b
    1526536161481 Enik-Bock    en-US fr-FR Delivered
    1526536161481 Enik-Bock en-US de-DE Delivered
    1526536145347 DBS-Fastrack en-US fr-FR Completed
    1526536145347 DBS-Fastrack en-US de-DE Completed
    1526536135589 Fastrack en-US fr-FR Delivered
    1526536135589 Fastrack en-US de-DE Delivered
  • Filter by status and list jobs

    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -b -st Delivered
    1526536161481 Enik-Bock  en-US fr-FR Delivered
    1526536161481 Enik-Bock en-US de-DE Delivered
    1526536135589 Fastrack en-US fr-FR Delivered
    1526536135589 Fastrack en-US de-DE Delivered
  • List job with pagenumber and pagesize

    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -b -ps 10 -pn 7
  • Get wordcount for a job

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -w wordcount for job id Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -w 1523008787812
    fr-FR No-Match 354 Fuzzy 0 100% Match 0 Gold 0 Repetitions 47 Total 401
    de-DE No-Match 354 Fuzzy 0 100% Match 0 Gold 0 Repetitions 47 Total 401

Upload files

  • Upload file(s)

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -a dir or file to upload Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -a e:\samples\
  • Upload file

    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -a e:\samples\Europe.docx
  • List all files uploaded but not submitted

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -r list files (defaults to listing all unsubmitted files) Yes  
    -ps page size to request No  
    -pn page number to request No  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -r
  • List file with page size and page number

    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -r -ps 5 pn 10
  • Submit unsubmitted list to GCC

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -i Job Name Yes  
    -s Source Locale of job Yes  
    -t Target Locale of job Yes Yes 
    -o Due Date offset in days Yes  
    -ins Translation Instructions No  
    -fid List of fileIds to include No Yes
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -i ThisJobName -s en-US -t fr-FR,de-DE -o 5 -ins "Use MS StyleGuide"
    2018 05 10 12:18:54 d2aa8de5-7dfb-448a-a748-9ef8ff6fdfb3 paragram.docx
    2018 05 11 17:27:15 455e8c03-acfe-4bd2-839d-a2ffb909a96a sample.doc
    2018 05 11 17:27:17 5d9a84b0-4b1b-4dd9-b0c1-8a627b51af1d sample01.doc
    2018 05 18 14:33:40 fb4146a5-a98d-4b74-b731-0cc2d69360c5 werther.docx
    2018 05 23 16:29:48 02bee869-6481-42e9-a987-c7385eaff560 kafka.docx
    Job created 1527556965524
  • Submit specific fileIds to GCC

    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -i ThisJobName -s en-US -t fr-FR,de-DE -o 5 -fid
    d2aa8de5-7dfb-448a-a748-9ef8ff6fdfb3,5d9a84b0-4b1b-4dd9-b0c1-8a627b51af1 

Download Files

  • List all files for a job

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -k job id Yes  
    -st job status No Yes
    -pn page number to request No  
    -ps page size to request No  
    -t Target locale for job No Yes
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -k myJobId
    /files/ep1.properties                 2016-08-04T08:18:14Z  javaProperties
    /files/ep2.properties                 2016-08-04T08:30:44Z  javaProperties
    /files/ep5.properties                 2016-08-10T14:04:45Z  javaProperties
  • List files with page size and page number

    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -k myJobId -ps 10 -pn 10
  • Download all files

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -d Job Id to download Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -d myJobId
    downloaded werther_es-ES.xml 
    downloaded paragram_fr-FR.docx 
    downloaded kafka_de-DE.docx
    downloaded test_fr-FR.xml 
    downloaded test_fr-FR.xml
  • Confirm delivery

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -n Job Id to download and confirm Yes
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -n myJobId
  • Download Task

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -dt Task Id to download Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -dt taskId
  • Download and Confirm Task download

    Options Description Required Multiple
    -to user session token Yes  
    -l GCC Url Yes  
    -c connector key Yes  
    -nt Task Id to download Yes  
    $ java -jar globallink-gcc-cli-x.x.x.jar -to session-token -c 90381xxxxxxxxxxxxxxxxxxxx -l https://connect-dev.translations.com/api/v1 -nt taskId

Callback Handler

Overview

Webhooks are user-defined HTTP callbacks that are usually triggered by an event, such as successful analysis or completion of a job. When that event occurs, GlobalLink Connect makes an HTTP request to the callback URL configured for the webhook. Users can configure them to cause events on GlobalLink Connect to invoke behavior on another system.

The list of events that emit a callback are:

  1. Anaylzed
  2. Submission Complete
  3. Job Completed
  4. Submission Delivered
  5. Job Delivered
  6. Submission Delivered

GL Callback Handler is a sample node js application which can be deployed on your server to accept the event based HTTP POST notification from GCC.

How it Works

Pre-Requisites

  • Server with public IP or domain name
  • Node version 8.9.4
  • Install pm2 using following command
    npm install pm2 -g

Deployment Process

  1. Create a directory and place the Callback handler build in it.
  2. Open a terminal and navigate to the build folder.
  3. Run the npm install command.
  4. Start the process using
    pm2 start server.js --name callback-app
  5. The application will start on port 9005. If you want to change the port, edit the server.js file, change the port, and restart the service using pm2 restart.

Once your service is up, the application would accept all the post notification on /test_callback endpoint. So your URL would be:

https://{IP/ Domain name}:9005/test_callback

Usage

This URL should be passed as value for parameter callback_url in /submission/submit or /submission/create API endpoint. GCC then sends a json notification to this URL each time an event is triggered. All the event information is stored in a file called callback.json which can be read and used for your integration.