We have always known that some translation companies invest in their own technology and have developed their custom business management system (BMS). However, it was not until we started BeLazy that we found out that the number is actually much bigger than we ever expected — both those who serve enterprise clients on a program basis and also those who work for these large multi language vendors. Given most of them are keen on automating processes, we have received several inquiries from this group of companies. As a result, we have created the following piece that explains what to expect when you integrate your system with BeLazy and go over best practices for making sure that it happens smoothly.
Note: We also offer dedicated onboarding services where we take you through all of these steps to guarantee the success of the project while offering you practical and custom advice.
In this example, we assume that you want to do the integration yourself. However, we can also develop the integration to your system as a paid service if you have a well-documented API. Without well-documented APIs the integration is practically impossible. So far we have only seen large language service providers offering documented APIs.
We only cover the process of project creation, rather than end-to-end project automation. Why? Simply because project creation is the first step towards seamless automation and it can be implemented separately.
This example includes tasks and action items for two different roles: The software developer, who implements the APIs, and the project manager who is the specialist regarding the company’s translation processes and vendor portals/TMSes. In our model, the project manager formulates the instructions for the software developer, who then finalizes the code which is ultimately approved by the project manager.
So we made a decision, what next?
BeLazy is an integration platform for translation management systems and vendor portals. With a single integration with your BMS, you get access to any of our supported systems. Some companies decide to integrate on a per-account basis while others decide to rely on BeLazy for the management of all their integrations.
If you have already developed integrations with TMSes and vendor portals into your business management system, don’t worry, you don’t need to replace them with BeLazy’s integrations unless you want to. We complement your existing pool of integrations set and we believe that by using BeLazy you won’t ever have to worry about additional connectors.
At this stage you may be wondering how much effort this integration requires! Companies have reported that they managed to implement project creation within 40-200 hours of development. We believe this guidance will get you closer to the lower end of the range.
Let the onboarding start
Action items for the developer:
- Nothing so far
Action items for the project manager:
- Create an account
- Create the first connection - just try to edit the automation.
Set up a webhook (callback)
There are two ways of checking for projects in BeLazy. The first one is to set up a scheduled task directly from your BMS to look up what’s new in BeLazy. The second one is to let BeLazy indicate to your system every time you have a new project accepted. The second solution is superior but a little bit more complex as it requires setting up a webhook.
Developers are advised to pay attention to CORS errors.
Action items for the developer:
- Nothing here. The webhook information will be needed during the next step.
Action items for the project manager:
- Create an account
- Create the first connection - just try to edit the automation.
Configure the values to map
One of the main advantages of BeLazy against custom integration is our top-notch error handling. With an integration almost anything can go wrong: The system may be down, there could have been an update, it may reject your query of downloading more than 50 MBs, the password might have changed, the project you’re trying to query may not have a price attached and so on.
One big chunk of the development work is error handling and the other one is mapping. Mapping means corresponding the way project metadata is named in your system with how it’s named in the customer’s system:
- what the customer calls translation in their system is TEP (Translation Editing & Proofreading) in yours,
- they may include matches such as Partial MT post-editing (words) which for you is equivalent to a 75-84% match payment,
- they may use the term source words instead of just words.
The list goes on, that’s why we take care of translating all these values from system to system.
Given the majority of custom-developed systems do not have a full API for querying all these values, we offer the possibility of uploading a list of them into BeLazy, which you can later on modify, with either a reimport or manual editing. The software developer needs to prepare these values and get them into a simple JSON file, as the example shows on this page.
If your system does not support some of the value types we ask you to upload, don’t worry. The original value from the translation management system or the vendor portal will still be available in your project listing.
Action items for the developer:
- Extract the values into a JSON file.
Action items for the project manager:
- Configure the business management system in BeLazy.
- Creating the mapping for each connection by editing the automation.
- Enter the webhook information received in the previous step during the automation.
Understanding the JSON reply
The next step is to query some projects from BeLazy. We use Postman to test the API responses, which can also be used by a tech-savvy technical project manager. Install it, go to https://api.belazy.cat/reference/ and download the OpenAPI specification which you can import into Postman. Click on Import and upload the swagger.json file.
To query projects, you have to use the Projects / List projects call. It’s under Projects / v1, List projects. By default, when you open this call in Postman, it will give you all the options enabled, and it won’t have the authorization set up yet.
First go to Headers, and add a new header: Authorization should be the key of the header, and the value should be ApiKey {ApiKey} where {ApiKey} needs to be substituted with the long random Api access token that you can copy out from BeLazy’s Api Access Tokens option from the Profile menu. Make sure that the value includes also the word ApiKey, not just this long string. Now go back to Params, and disable all of the parameters by removing the checkmark, and click Send. Postman now communicates with BeLazy and should send you the JSON response back.
PRO TIP: By default the JSON will include projects seen but not yet accepted by BeLazy, which helps do the set up without affecting the current manual workflow. If your connection comes without projects and you don’t receive anything back, BeLazy can offer you sample projects. Under Headers, add the X-BeLazy-Test key and enter any value – e.g. an “x” will do. This way, BeLazy will offer two sample projects for testing.
Once you manage to download a JSON, the next step is to annotate what goes where. This is a huge help – a specification – for the developer. Copy or save the resulting JSON file, and open it in a text editor. The project manager who already worked with the translation management system or vendor portal should find most of these values familiar.
Quick help: information about each project is delivered in three representations. Always look for any information you want to extract first under destination. If you don’t find it there, look under beLazy and only then under origin.
You can simply write next to each value in the JSON file where you want it to appear in your system. Be thorough and clear and check whether the developer understands your observations. After having entered all these comments, it’s not a valid JSON file anymore – it has become a documentation for your needs.
When documenting your desired values, you should also consult this page. It contains a description of information specific to different translation management systems and vendor portals. You need to decide if you need these data in your system, and if so, also map them there. This you can use as another piece of the specification.
Action items for the developer:
- Discuss the project specification with the project manager.
Action items for the project manager:
- Retrieve a JSON file (may request help from the developer) and annotate it based on the values you see there and the project extraData. For each value, starting with destination, indicate whether you need to see it in your system and if so, where.
PRO TIP: As a minimum, annotate a single project from a single connection. If you annotate a project from more than one connection, you will save yourself a headache later when you want to add more connections. Two are way better than one.
Implementation
● In the List Projects query, the Status you select should be Accepted.
● Keep in mind that there is a Count, and there is paging. You should implement the code to support paging if there are more projects than the value in the Count attribute.
● Every project that you successfully created should be acknowledged. If you don’t do this, we will send you reminders. If you don’t acknowledge a project after a certain period of time, we could deactivate your access.
Action items for the developer:
- Development and testing.
Action items for the project manager:
- Remind the developer about acknowledging projects (otherwise they don’t disappear from the projects approval UI of BeLazy).
- Check and test the finished implementation.
Moving forward
If you managed to complete all these steps, you now have everything to take the integration up to the first level (project creation). The second step is project automation, which includes vendor reassignment, task delivery and closing. You will have to call BeLazy from different points where you can change the vendor or you can finish a task or a project in your system.
Please expect a detailed article on the topic in a few months’ time. Happy coding!
