Announcing Knock Translations

Today we’re thrilled to announce Knock translations.

Translations are a new addition to the Knock model and API that let engineering and product teams manage notification localization at global scale, without incurring high amounts of notification template debt along the way.

Read on to learn why we built translations, the path we took to the product we’re launching today (and what we learned in the process), and how you can get started using Knock to power message localization.

Notification localization is a hard problem to solve at scale

The “why” behind notification translation is simple. You send product notifications to deliver relevant updates to your users and to help them get value out of your product. For users that speak a language other than your default, that value is delivered faster when your messaging is in their language of choice.

But while the value of notification localization is simple to understand, how to support it and build it into your notification system is another story.

For teams building notifications in-house, there are a number of internationalization (i18n) frameworks (such as i18next) you can use to translate both front-end product copy as well as the copy you use in your notifications. But building notifications in-house comes with its own set of challenges which we’ve written about in depth before on the Knock blog.

For those teams looking to bring notification localization out of their home-rolled system and into a 3rd-party platform, the options aren't great.

In most 3rd-party messaging vendors, localization is supported by creating per-language versions of each of your existing notification templates. As an example, if you have a welcome email template written in English and you want to support it in Spanish and French, you create two new email templates—one for each new language.

This sounds simple in theory, but in practice it quickly turns into a maintenance nightmare.

A quick demonstration on how this becomes a problem at scale:

• 10 notification types * 3 languages = 30 templates to maintain
• 30 notification types * 30 languages = 900 templates to maintain 🙃

We learned this the hard way when we launched our original translations beta release last December. We had based our original template localization design on the model we were used to in other tools — each notification template had its own language-specific variants. Then we rolled it out to our first beta partners and realized that at true production-scale (30+ languages) we’d created a new problem for our customers: they’d have to manage hundreds of template variants. This is the standard for messaging platforms today, but we knew there had to be a better way.

We went back to the drawing board with the following principles in mind:

• The amount of work associated with localization updates should scale linearly (not exponentially) with notification template and language count.
• It should be easy to preview a given template across locales to identify missing translations.
• Developers should be able to update translations programmatically, so the translations can feed into the localization framework they use in the rest of their product.

After months of hard work (and throwing out our first localization beta), we’re proud of the solution we've built. It ships today.

Introducing Knock translations

Knock translations brings the locale-specific translation file approach of frameworks such as i18next and Shopify locales (both of which served as design inspirations for this release) into our notification system.

With Knock translations, localization is handled within one part of the model and notification templates in another. This means when you introduce support for a 31st language into a product with 30 different notification types, you’re updating one file, not 30. Here’s how.

How it works

In Knock i18n, each language you want to support is a JSON file that contains translation strings.

Here’s an example of two translation files within Knock.

// The JSON file for English (en.json)
{
  "greeting" : "Hello",
  "welcomeMessage" : "Welcome to Jurassic Park!",
  "actions" : {
    "generic" : "Learn more",
    "comment" : "View comment",
    "page" : "View page"
  }
}

// The JSON file for Spanish (es.json)
{
  "greeting" : "Hola",
  "welcomeMessage" : "Bienvenido a Jurassic Park!",
  "actions" : {
    "generic" : "Aprender más",
    "comment" : "Ver comentario",
    "page" : "Ver página"
  }
}

To translate a notification, you reference your translation files using a liquid helper in your Knock templates, like this:

// A simple notification that we'll translate for our users.

{{ "greeting" | t }},

{{ "welcomeMessage" | t }}

{{ 'actions.generic' | t }}

When we send this notification to a given user, we look for the locale stored on that user and generate the template based on the translation strings you’ve stored within the corresponding translation file.

As an example, in the case above, here’s what English and Spanish users receive.

Through this example you can see how Knock translations enables teams to localize notifications for users in different locales, ***without******* introducing the exponential maintenance overhead of managing per-locale templates for every notification you send.

This model also supports interpolation and pluralization so you can easily create personalized, localized notifications for your users.

Here are a few additional benefits of the translation model we've built at Knock.

A localization system that scales

By separating translation strings from your actual notification templates, the Knock localization system ensures separation of concerns and helps reduce duplicative work often associated with notification localization.

If we take the example above again, we can see what happens when we need to make changes to the Knock system.

• When we need to introduce a new language, we just need to add one new translation file. Once it’s in production, our users from that locale will automatically start receiving translated notifications.
• If we want to update an existing notification, we only have to update one template. Its changes will automatically apply to all locales.
• If we want to introduce a new notification, we just add one new template and then make sure any translations it needs are present across our translation files.

This is a translation system that reduces future maintenance and can easily scale into a notification system sending hundreds of templates across 50+ languages.

We’ve also added namespace support for translation files. This means that if you want to create different translation files for a given locale (to help with translation string organization), you can.

Preview locale-specific templates with ease

The Knock translation-template model makes it easy to preview what a given notification template will look like for a given locale. Just navigate to the Knock template preview and select the language in which you want to see your notification. Instead of switching between different templates as you would need to in other tools, in Knock there’s just one template to preview.

In the future, we’ll be introducing ways to validate that a given template has translation strings supported for all relevant locales to make it even easier to manage your localization proactively and ensure a user always gets a complete, translated notification.

Update translations via the Knock API and CLI

When you manage translations in your codebase for other parts of your application, it’s not ideal to have to separately manage them in a third-party tool. That’s why we’re adding translation support to the Knock API and CLI.

With the Knock CLI, you can pull down existing translations in your Knock account and work with them locally, then push them back up to Knock to use in your notification localization. We also enable you to programmatically update your translations and promote them to production from your own development workflow.

This means that you can update translation files in your own framework as part of your application code and then build those files into Knock translation-spec files and promote those Knock translations to production, all as part of your build and deployment pipeline workflow.

If you’re a developer that’s had to manage notification translation in the past (and/or had to so in third-party tools), this is going to save you a lot of time. 😁

The Knock CLI is currently in beta. If you’re interested in joining the waitlist to work with translations via our API, please send us a note.

How to get started

If you’re a team that’s powering notification localization today and looking for a better way, we’d love to talk with you. The best place to start learning about how Knock can help with translations is in our docs.

Knock translations are now generally available for customers on our Growth and Enterprise plans. If you want to start a 30-day trial, please contact us.

Frequently asked questions

Q: How much does it cost to use Knock translations?

Knock translations are available on our Growth and Enterprise plans. There is no usage cost associated with Knock translations.

Q: Is there a limit to how many locales I can use with Knock?

No, there is no locale limit in Knock.

Q: Which locales and languages does Knock support today?

Knock supports ISO 639-1 two-character language codes in combination wit ISO 3166-1 country codes. This means you can create an en translation for all English speakers, and then create an en-US translation for English speakers in the United States. Here is the full list of Knock’s supported locales and languages.

Q: I use another customer engagement platform today for notification localization. How can I move into Knock?

We offer template and translation migration services for enterprise customers. You can learn more by contacting our sales team.