Review these guidelines to ensure that the first version of your Connector will:
- have the features required for a production environment
- meet the Lionbridge Connector Certification requirements
After you develop your Connector, the Lionbridge Connector team will use these guidelines as the basis to certify it.
Over time, the Lionbridge Content API development team releases and deploys new API versions to support bug fixes and enhancements. The Content API development team follows these principles in its ongoing development for minor version upgrades, for example, 1.10.0 to 1.11.0:
- A method may support additional parameters, however these new parameters will be optional. If a new value or a default value is absent, the API will maintain its previous behavior. All methods are backward compatible.
- New properties may be added to existing models. These new properties will not change the meaning of existing properties within the model. All properties are backward compatible.
- A method can reject any request containing an invalid parameter or invalid header values.
Warning: Malformed requests that were accepted in previous releases, due to loose parsing logic, may result in a bad request response in future releases.
Typically, the content system defines how to install the Connector. Lionbridge recommends the following standards, while respecting the content system's requirements:
|Requirement||Installer must support installing, uninstalling, and upgrading the Connector. Upgrading should not impact in-progress jobs.|
|Recommendation||The installer should not require restarting the content system.|
|Recommendation||Installer should support enabling and disabling the Connector. Most content systems support active and inactive software components.|
|Recommendation||Installation should query existing version to ensure compatibility before upgrading.|
The Connector logs transaction information, including errors.
|Requirement||Application must write transaction information to a log file.|
|Requirement||Application must create a new log file every day.|
Application should support multiple logging levels, because Lionbridge Connectors support two logging levels:
|Recommendation||Application should provide a user interface to locate, consume, and possibly download log files.|
Application should clearly indicate that it reports and handles errors encountered while submitting translation jobs.
By default, Content API throttles all client organizations. For Prod environment, each IP is throttled to 20 requests per second max; for Staging environment, each IP is throttled to 10 requests per second max. Please note that the limit is subject to change without notice.
Integrations code should always check for HTTP response code 429 and 503 (retryable errors). If the response contains a "retry-after" attribute, then retry the request after that time; otherwise the integration should implement exponential backoff retry logic with limited number of retries.
Disclaimer: the following quota limitations are subject to changes.
The payload quotas ensure that the provisioned server resources can adequately handle workloads. You can increase these quotas on a case-by-case basis. The following table lists quota names and their default values.
|MaxJobsPerUser||Maximum number of concurrent submitted jobs per user.||1000|
|MaxListenersPerSite||Maximum number of listeners in the user's organization.||100|
|MaxStatusUpdatesPerSite||Maximum number of status updates in the user's organization.||10000|
|MaxReqsPerJob||Maximum number of requests (content items) per translation job.||1000|
|MaxSupportAssetsPerJob||Maximum number of support assets per translation job.||1000|
|MaxFilesPerJob||Maximum number of files per translation job.||1000|
|N/A||Maximum file size.||1 GB|
|N/A||Ability to clone a previously delivered job to resubmit it as a new job.||N/A|
These quotas are per Lionbridge client, and they are based on the expectation that the client will periodically clean up and delete old jobs. The quotas ensure that the provisioned server resources can adequately handle workloads. If it is likely that you will exceed these quotas, please contact Lionbridge to request an exemption.
XML files within the Payload
|Requirement||Application must split content into multiple files based on localization requirements. For example, separate SEO content from non-SEO content.|
|Requirement||Application must present as much context as possible. For example, within the payload XML, Lionbridge should be able to identify the H1, H2, and H3 headings, etc.|
|Recommendation||Application should provide as much metadata as possible to Lionbridge. Lionbridge can parse out anything not required or that has no value. Construct the payload so that applying an XLST will provide a faithful rendering.|
Typically the Connector has configuration options that an administrator can modify to affect the software performance. For version 1.0 releases, a graphical administration user interface is not required. An administrator can configure these options via a configuration file.
|Requirement||Application must support an administrator specifying configuration options via an editable configuration file stored locally on the file system or some other method, to control the application settings described in this section. For the initial release, an administration graphical user interface (GUI) is not required.|
|Recommendation||Application should support an administrator changing configuration options without restarting the content system.|
|Requirement||Application must support an administrator adding new translation providers via an editable configuration file or another interface.|
|Requirement||Application must support an administrator setting the application logging level to either Default or Debug. The default level is Default. For details, see Logging, above.|
|Requirement||Application must support configuring which providers are available for users to select. This feature limits user choices to those relevant to a particular application instance, and it prevents users from selecting the wrong provider.|
|Recommendation||Application should support defining the maximum number of items in an XML file.|
Application should support an administrator specifying the following standard proxy implementation settings, where applicable:
|Requirement||Application must enable users to map content-system languages to language codes accepted by Lionbridge. For a list of language codes, see Supported language codes.|
Keeping the application and database versions synchronized is a critical component of normal Connector operations. It also facilitates support and troubleshooting.
|Requirement||The Connector must write its version information to the log files on instantiation.|
|Requirement||The Connector must write relevant configuration information (such API keys and metadata) to the log files on instantiation.|
|Requirement||The Connector must include the ConnectorName and ConnectorVersion metadata fields in parameters in the endpoints for creating (POST) and modifying (PUT) jobs. They will also be returned in responses that return job details. These metadata fields support troubleshooting. Before certification, please obtain these value from Lionbridge Connectors Support, which you can contact by email at firstname.lastname@example.org.|
The following user interfaces are required in all Connectors. The user interfaces should respect the design and operational considerations of the content system.
|Requirement||individual item selection||Users can select a single item and send it directly to translation or to the Translation Queue.|
|Requirement||job creation||Application must restrict the maximum string limit of the jobName and requestName to 250 bytes each.|
|Requirement||Translation Queue||Users must approve items in the Translation Queue to send them out for translation.|
|Requirement||Bulk Translation||Users can select and send multiple items for translation in a few steps. This is often a wizard.|
|Requirement||Translation Status||Users can monitor the translation status of jobs and individual items sent for translation.|
The Connector must include the following functionality across the UIs described above. Each content system may implement these features differently.
|Requirement||The user can specify the source language for a translation job.|
|Requirement||The user can specify the target language for a translation job.|
|Requirement||The user can specify multiple target languages for a translation job.|
|Requirement||The user can search for content items by string.|
|Requirement||The user can search for content items in the content tree, including child items.|
|Requirement||The user can select one, multiple, or all items from a result set to send for translation.|
|Requirement||The user can filter results sets by criteria, including strings and dates.|
|Requirement||The user can send items to Translation Queue.|
|Requirement||The user can send items immediately for translation.|
|Requirement||The user can define job metadata: The standard base set includes: job name, job description, purchase order.|
|Recommendation||The user can define additional job metadata, including: delivery date, SEO required, special instructions, analysis codes, etc.|
|Requirement||The user can check job status via the Translation Status user interface.|
|Requirement||The application must check for and accept the redelivery of a job.|
|Recommendation||Before a redelivery, the application should check and warn for updated content. This reduces the risk of a redelivery overwriting content that has been updated by a user.|
The application must support users checking for job status changes. Use listeners so that the Content API pushes updates. If you use polling, use StatusUpdate for each job endpoint. In addition, the application should have an auxiliary way to query and retrieve translated content in case of malfunctioning listener endpoints or status update expiration.
Notes: Use only one listener of each type. If the user created a listener, the Content API implicitly acknowledges StatusUpdate of user jobs before the listener request is delivered. For example, if the listener endpoint is down, the Content API acknowledges StatusUpdate, and it is not included in a query.
|Requirement||The application must not allow users to cancel or delete jobs that are in progress.|
|Requirement||The application must respond correctly to the cancellation status in the API.|
|Recommendation||The application should support a multi-workflow model.|
|Recommendation||The application should support including reference material with the payload. Alternatively, you can pass information (instructions) via the description field in Content API. This is text input, restricted to 500 characters downstream. The application should support including additional information as a reference file.|
|Recommendation||The application should support users requesting a quote for a job.|
|Recommendation||The application should hiding completed jobs from the user interface a after configurable time period, for example, a specified number of days.|
The application should support users approving requests in jobs, if they are satisfied with the translated content, or rejecting requests in jobs, to reject the translated content for either quality or technical reasons.
The Connector uses notifications to send job information to administrators and end users.
|Requirement||The application must send notifications when it sends out a job for translation.|
|Requirement||The application must send notifications when a job returns from translation.|
|Recommendation||An administrator should define email-server information, including hostname, credentials and protocols to use.|
|Recommendation||Extend the default feature set. Additional features would include notifications when jobs fail, etc.|
Team profiles support separating groups of users, their content, and their jobs.
|Requirement||The application must support assigning specific providers to specific environments or user groups.|
|Nice to have||This feature varies depending on the content system. The goal is to store translated content locally, then compare translation requests, or compare field-level time stamps, if that functionality exists. The goal is to reduce the payload, so that it is only the delta between deliveries.|
The Content API uses push notifications, which supports polling.
The Connector can poll the Content API for translated content that the translation provider delivers. Polling is useful in the following scenarios:
When using polling, use a default frequency of 60 minutes. If required, you can configure a shorter polling frequency. However, for large file payloads, a longer polling frequency is recommended.
|Requirement||Passwords must be hashed and not stored in cleartext.|
Best practices in Connector development
|Implement a catch-and-retry for
||Occasionally, the API can experience load spikes that require additional system resources. The back end is designed to scale up when these are detected. However, there may be a delay before these capacities are available. There is also a rate throttling limit for API requests that users can hit when making a lot of API requests in a short amount of time.|
|Introduce a slight delay between method invocations when iterating over a large number of jobs or requests. This smooths out the load spikes.|
Set the Accept request-header field to the expected response content type, when retrieving the translated file from the API. For most use cases, setting the field to application/octet-stream will suffice.
|This prevents the situation of receiving a base64 string instead of the expected translated file.|
|Enable mashing payload files together.||This avoids hundreds of files in a single payload file.|
|Retrieve at the job level (as opposed to the file level).|
|Use the LL-CC format for the language codes, listed in Supported language codes.|
|Validate your language list.||This prevents a situation where you programmed
|Create as much business logic within the Connector as possible.||For example, with job approval, ensure that after delivery the translated content does not become publicly available until after a user reviews and accepts it. This can be configurable by the user.|
|Connectors should include a User Guide and an Installation Guide for effective support post deployment.||Documentation enables users to be self-sufficient.|
|If you have any questions about the process or the best practices described this document...||If you have any questions during the development process...||After you have developed your Connector...|
|Please email email@example.com to contact the Lionbridge Connector Team.|
|We can set up a call with you.||We can answer your questions.||
Request a certification meeting with Lionbridge to certify the Connector for production use.
Note: Certification is required before Production access is granted.
|ar-AE||Arabic (United Arab Emirates)|
|ar-SA||Arabic (Saudi Arabia)|
|ar-XN||Arabic (International) [Modern Standard]|
|en-cpe||Creoles and pidgins, English-based (Other)|
|en-gb||English (United Kingdom)|
|en-HK||English (Hong Kong)|
|en-LK||English (Sri Lanka)|
|en-nz||English (New Zealand)|
|en-SA||English (Saudi Arabia)|
|en-us||English (United States)|
|en-za||English (South Africa)|
|es-CR||Spanish (Costa Rica)|
|es-DO||Spanish (Dominican Republic)|
|es-pr||Spanish (Puerto Rico)|
|es-SV||Spanish (El Salvador)|
|es-US||Spanish (United States)|
|es-XL||Spanish (Latin America)|
|fr-011||French (West and Central Africa)|
|fr-CD||French (DR Congo)|
|fr-CI||French (Ivory Coast)|
|ho-PG||Hiri Motu (Papua New Guinea)|
|hr-ba||Croatian (Bosnia and Herzegovina)|
|jam-jm||Jamaican Patois (Patwa)|
|ku-IQ||Kurdish, Central [Sorani]|
|ku-TR||Kurdish, Northern [Kurmanji]|
|nd-ZW||Ndebele, Northern [Sindebele]|
|nl-NL||Dutch (The Netherlands)|
|nso-ZA||Sotho, Northern [Pedi, Sepedi]|
|rom-MK||Romani, Vlax (Romania)|
|sgn-GB||Sign Language, British|
|sr-Latn-ME||Serbian [Latin] (Montenegro)|
|st-LS||Sotho, Southern [Sesotho]|
|ta-LK||Tamil (Sri Lanka)|
|tpi-PG||Tok Pisin (Papua New Guinea)|
|wuu-CN-CN||Wu Chinese [Shanghainese]|
|zh-hk||Chinese (Hong Kong)|