Skip to main content
All CollectionsTranslations
Knak Custom Translation Integration Setup Guide
Knak Custom Translation Integration Setup Guide

A step-by-step process to help you set up your custom translation integration

Spencer Bull avatar
Written by Spencer Bull
Updated over 3 months ago

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

Creating an API role

  1. Open Knak Builder and navigate to Admin (top left button)

  2. Navigate to Company > Roles > + Create Role

  3. Add the Request Translations and Can Manage API Tokens permissions

    • Optional permission you can add is Request Translations for Unapproved Email

  4. Click Create

Creating an API user

  1. Navigate to Company > Users > Invite User

  2. 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.

  3. In Select Roles add the role that was created above

  4. Click Save User and Send Invite

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 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.

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’.

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 for the languages you selected on the right-hand translate menu.

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.

  1. Create translation requests in Knak using the custom translation integration

  2. Query for translation requests via the API

  3. Fetch metadata for new translation requests via the API

  4. Fetch the translation source file for translation requests via the API

  5. Process the translation source file in your custom translation tool

  6. Upload the translated file to a translation request via the API

  7. View the translated variant of the completed translation request in the Knak editor

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.


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

Did this answer your question?