Understand the Sample Translation Connector Source Code

The source code of the sample translation connector contains REST APIs and a job manager to handle creation and persistence of the connector jobs.

The sample translation connector contains a set of REST APIs implemented using the Oracle Content Management connector interfaces. This is implemented as per the JAX-RS specification.

The job manager uses persistenceApi to store the following resources:

• Metadata about the job in the connector and the project created in the Language Service Provider
• Contents of the translation zip file from Oracle Content Management
• Metadata about each file and the corresponding document in the Language Service Provider
• Combination of the translations with the original files
• Creation of the translated zip file for the connector

The persistenceApi included in the sample simply uses the files system to manage these resources. A full translation connector implementation will need to make sure that the persistence layer will continue to work during failover and upgrade as well as provide secure access to the resources stored.

The job manager also maintains information in the connector job metadata file about the status of a translation job in the Language Service Provider by querying the information back either via polling or via a callback.

Code Structure:

connector:

• SampleConnectorRouter.js
  • Authenticates the request
  • Extracts parameters from the request URL
  • Maps the request URL to the corresponding SampleConnector function:

    	GET: /api/connector/v1/server => getServer() – metadata about the connector
    	POST: /api/connector/v1/job => createJob()
    	GET: /api/connector/v1/job/:id => getJob()
    	POST: /api/connector/v1/job/:id/translate => translateJob() – accepts a zipfile
    	GET: /api/connector/v1/job/:id/translation => getTranslation – get translated zip
    	DELETE: /api/connector/v1/job/:id => deleteJob()
    

• SampleConnector.js
  • Validates the request parameters
  • Calls the appropriate connector code
  • Formats the response
• SampleBasicAuth.js

connector/job-manager:

• sampleJobManager.js
  • Expand the zip file and then, for each file:
    • Filter the file to include only translatable fields
    • Submit the translatable fields to the LSP
    • Wait for the translations to come back (either by polling or by callbacks)
    • Recombine the translatable fields with the original files
    • Create a zip file of all the translations
  • Also restarts any running jobs on startup to support failover
• sampleFileImporter.js
  • Imports the filtered document into the LSP specifying the source language
• sampleFileTranslator.js
  • Asks the LSP to translate the documents into the target languages
• sampleFileDownloader.js
  • Downloads translations for a document

connector/apis:

• persistenceApi.js
  • Basic implementation using the filesystem to:
    • Unpack the zip file and maintaining the source
    • Accept translated files and creates the expected zip structure
    • Zip up and return the translated files
• filterApi.js
  • Extracts translatable strings from the source files based on file type
  • Recombines the translated strings with the source file
• connectorApi.js
  • Constructs the requests to the LSP
• httpApi.js
  • Makes the actual GET/POST requests to the LSP

MockServer:

• mockLSPServer.js
• mockBearerAuth.js
  • A mock LSP server
  • It expects the following headers:
    • BearerToken – can be any Bearer #### value
    • WorkflowId – supports only machine-workflow-id

Translation Job Original Zip File Format

The connector is responsible for extracting the files to be translated from the translation zip file, filtering them, and sending them to the LSP. To do this, the connnector needs to understand the format of the zip file.

There are two types of translation jobs in Oracle Content Management, so there are two file structures possible in the zip file:

• Asset Translation
  • Zip file format
    • "job.json" - Contains details on the source & target languages.
    • "root"
      • <asset files to be translated>
• Site Translation
  • Zip file format
    • "site"
      • "job.json" - Contains details on the source and target languages.
      • "root"
        • <site files to be translated>
    • "assets"
      • "job.json" - Contains details on the source and target languages.
      • "root"
        • <asset files in the site to be translated>

Translation Job Translated Zip File Format

On successful translation, the connector must recombine the translations with the original files and create a zip file in the following format, which is based on the original format.

• Asset Translation
  • Zip file format:
    • "job.json"
    • "de-DE"
      • <asset files>
    • "fr-FR"
      • <asset files>
    • "it-IT"
      • <asset files>
    • "root" (Original files can optionally be included. The directories also need to be included, and not just the files.)
      • <asset files>

• Site Translation
  • Zip file format:
    • "site"
      • "job.json"
      • "de-DE"
        • <site files>
      • "fr-FR"
        • <site files>
      • "it-IT"
        • <site files>
      • "root" (Original files can optionally be included. The directories also need to be included, and not just the files.)
        • <site files>
    • "assets"
      • "job.json"
      • "de-DE"
        • <asset files>
      • "fr-FR"
        • <asset files>
      • "it-IT"
        • <asset files>
      • "root" (Original files can optionally be included. The directories also need to be included, and not just the files.)
        • <asset files>