Real-time message translation is available on the Premium plan and up.

Even users who don't speak the same language need to be able to communicate. In order to make that easier, TalkJS can leverage the Google Cloud Translation API to translate users' messages in real-time. When translation is enabled for a conversation.

There are two things you need to do to set this up:

1. Obtain and configure a Google API key
2. Enable translation in the client SDK.

Obtaining and configuring a Google API key

1. If you don't have one yet, create a project in the Google Cloud Platform console.
2. Make sure that billing is enabled. See Google's documentation on enabling billing for more info.
3. Enable the Google Cloud Translation API for your project
4. Go to the credentials page, click "Create credentials" and select "API key".
5. Click the edit button next to the newly created API key, and configure it as follows:
   • You can give the API key any name you want.
   • From the "Application restrictions" list, select "HTTP referrers".
   • Click "Add an item", and enter https://app.talkjs.com
   • Under "API restrictions", click "Restrict key."
   • From the "Select APIs" dropdown, select the Google Cloud Translation API.
   • Click "Save".
6. Copy the API key and paste it into the TalkJS dashboard, then hit save.

Enabling translation in the JavaScript SDK

Translation settings are set per chat component, and are not kept in the user's browser, so you have full control over when translation is turned on or off.

Showing a translation toggle in the UI

You can pass a value for showTranslationToggle when calling createChatbox, createInbox or createPopup to display a link at the bottom of conversations that allows the user to turn translation on or off for that conversation. Setting it to true shows the toggle in all conversations, while setting it to "auto" only shows the toggle when there ae participants with different locales.

const inbox = session.createInbox({
    showTranslationToggle: "auto",
});

var inbox = window.talkSession.createInbox({
    showTranslationToggle: "auto",
});

Enabling translation for multilingual conversations

If you pass "auto" for translateConversations to createInbox, createChatbox or createPopup, translations will be enabled for any conversations in this UI where there are participants with different locales.

const inbox = session.createInbox({
    translateConversations: "auto",
});

var inbox = window.talkSession.createInbox({
    translateConversations: "auto",
});

You can also apply this setting to an existing UI, in which case it'll by applied to any conversations for which you haven't specifically turned translation on or off.

inbox.setTranslationEnabledDefault("auto")

Enabling translation for all conversations in a UI

If you pass a boolean value for translateConversations to createInbox, createChatbox or createPopup, translations will be enabled or disabled for all conversations shown in that UI.

const inbox = session.createInbox({
    translateConversations: true,
});

var inbox = window.talkSession.createInbox({
    translateConversations: true,
});

You can change this setting on an existing ui object as well

inbox.setTranslationEnabledDefault(true)

This will change the default translation setting, which is applied to any conversation for which you haven't specifically enabled or disabled translation.

Enabling translation per conversation

If you pass an array of conversation IDs or ConversationBuilders for translateConversations to createInbox, createChatbox or createPopup, translation will be enabled for those conversations, and disabled for all others by default.

const inbox = session.createInbox({
    translateConversations: ["conv_1", "conv_2"],
});

var inbox = window.talkSession.createInbox({
    translateConversations: ["conv_1", "conv_2"],
});

And to do this on an existing UI object:

inbox.setTranslationEnabledForConversation(conversation, true);