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
- Expand the zip file and then, for each file:
- 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
- Basic implementation using the filesystem to:
- 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
- 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
- BearerToken – can be any
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>
- Zip file format
- 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>
- "site"
- Zip file format
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>
- Zip file format:
- 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>
- "site"
- Zip file format: