Need to utilize your own translation tool within Knak? Follow this easy guide to get a custom translation integration working using the Knak public API. With a custom translation integration, you can initiate translations from the Knak builder and have your custom translations tool process and upload the translated versions of your Knak asset. Let’s get started!
API Setup
Create an API Role
Open Knak Builder and navigate to Admin (top left button)
Navigate to Company > Roles > + Create Role
Add the Request Translations and Can Manage API Tokens permissions
Optional permission you can add is Request Translations for Unapproved Email
Click Create
Create an API User
Navigate to Company > Users > Invite User
Enter an Email, First name and Last name. A confirmation email will be sent to the provided email address. You can utilize the "+" convention (e.g. youremail+api@domain.com) for your email address.
In Select Roles add the role that was created above
Click Save User and Send Invite
More info here: https://help.knak.io/en/articles/1731519-add-remove-users
Authentication
To allow your platform to access data in Knak, we recommend authenticating via the OAuth2 authentication method. When signing in to allow permissions to your OAuth2 application, make sure to use the API user you created earlier.
You can create OAuth applications here: https://enterprise.knak.io/account/oauth-applications
For information on how to use OAuth for authentication to the Knak API or on how to use an API token to authenticate, see https://enterprise.knak.io/docs/api#section/Overview/Authentication
Using the Integration
Creating an Integration
In Knak, navigate to the Admin > Integrations > Platforms page. Scroll down to the Translations section and create a new ‘Custom Translations Integration’.
Managing your integration
Now that your integration is set up, you can view its configuration, edit it, or delete it from the "My Platform Connection" list on the Integrations page.
If you need to connect a new integration – or re-add a previously deleted one – you can do so by scrolling down to the "All Platforms" section and clicking Connect or Add Another Connection on the relevant platform tile.
Creating a Webhook
Knak also supports webhooks that will send out events whenever new translation requests are created in your Knak instance. Setting up webhooks is easy, simply go to the Admin section and click on Integrations > Webhooks.
Create a new webhook and enter the necessary information (name, payload URL).
Under the ‘Subscribed Events’ section, select the asset.translation_requested event to subscribe to.
After creating a webhook, you will see in the integration tile for your custom translation integration that the webhook has been set up for that integration.
Creating Translation Requests
Once you have created a custom translation integration in Knak, you are ready to create translation requests for your assets!
Open a Knak asset, navigate to the ‘Translate’ tab, then click ‘Translate Now’. Select the custom translation integration, then go through the modal steps and select your target languages for translations. Finally, click ‘Submit Request’ to create the translation requests.
Once complete, you should see the translation requests on the right-hand translate menu for the languages you selected.
Using the Translations API
Now that you have translation requests for your Knak asset, you can start to query and process them by leveraging our translations API endpoints.
For all the available translation endpoints, see our official API documentation: https://enterprise.knak.io/docs/api#tag/TranslationRequests
The general flow that we recommend for performing translations via the API is as follows.
Create translation requests in Knak using the custom translation integration
Query for translation requests via the API
Or wait for webhook event to notify of new translation requests
Fetch metadata for new translation requests via the API
Fetch the translation source file for translation requests via the API
Process the translation source file in your custom translation tool
Upload the translated file to a translation request via the API
View the translated variant of the completed translation request in the Knak editor
FAQs
What is the language code format for translation requests?
By default, the format for language codes is a 2-character code that indicates the language. Below is a list of the default languages.
Language Code | Language Name |
zh | Chinese |
es | Spanish |
en | English |
hi | Hindi |
ar | Arabic |
pt | Portuguese |
ru | Russian |
ja | Japanese |
de | German |
ms | Malay |
id | Indonesian |
vi | Vietnamese |
ko | Korean |
fr | French |
it | Italian |
th | Thai |