Translations

Enabling translations and setting a default locale

First you’ll have to enable translations for your account and set a default locale. This will be the “fallback” locale - if a translation for a given recipient’s locale is missing, it will look for the translation in this default locale instead.

Go to “Settings” under your account name in the left sidebar and click “Enable translations” to select your locale. (You can always change this default language later.) Now, you should see a new “Translations” page under “Developers” in the sidebar. This is where you’ll be working with your translations.

Basic usage

Translations are a JSON object that contain the text for your messages in various locales. For example, let’s say you have a customer order notification you’re building and want to localize it for French and English users.

Once you have those translations created for the en and fr locales, you can reference their translation strings in your message templates like this:

Here's how this works: the translation helper looks up the recipient of the current workflow run, finds their locale, and then looks for the "OrderReady" key within the translation file for that locale. (If a translation file isn't found for a given recipient's locale, the default locale is used instead.)

The recipient must have a locale property set for the helper to find their translations. You can add properties to any of your users when you call the user identify endpoint.

For a recipient with a locale of en, they would see “Your order is ready” while a recipient with a locale of fr would see “Votre commande est prête”. If a recipient doesn't have their locale set, because our fallback locale is en they would also see "Your order is ready."

Working with translations

Translations follow the same version control flow in Knock as workflows and layouts. You create them in development and then promote them to subsequent environments.

Keep in mind this means that to see translation updates in development you'll need to commit your latest changes to the development environment.

You can view, manage, and archive translations within the "Translations" page under the "Developers" section of the Knock sidebar.

Creating a translation

In the translations page, click “Create translation” on the top right to make a new translation. You’ll select the locale and you’ll be able to supply an optional “namespace”. The namespace helps organize translations of the same locale so you can keep similar concepts together. You can see how to reference namespaced translations in your message templates here.

Keep in mind that you cannot create two translations with the same locale and namespace and you cannot edit a namespace - this helps preserve the references used within your message templates.

Editing a translation

Once you’ve created a translation, you can begin to add to it and edit the JSON directly. Make sure to “Save” it when you’re happy with it, and then you can click “Commit” to make it available in your development environment. You must use valid JSON, but there are no restrictions on the format of the keys or on how deeply nested you decide to build your translation.

Archiving a translation

From the list of translations, click the 3-dot menu next to the translation you want to archive and the option will appear if your role has the permissions to manage translations.

Using the t filter in your message templates

Knock supplies a t filter for you to reference your translations from within the message template. As shown above, you’ll reference the key of the translation you want to use followed by | t and it will supply the translation for the recipient’s locale. The t filter also allows you to use variables, other filters, and special pluralization rules as well, which we’ll cover here.

Variables and interpolation

You can and probably will often use variables inside of your translations. Let’s look at this translation example:

You can pass variables to the filter like this:

Where “actor” and “likedPhoto” are variables that get passed into your data payload and have a name and title key, respectively.

Pluralization

Translations sometimes need specialized pluralization rules. When you pass the count variable to a translation, it will know to look for a special set of keys within your translation to match it to. Those keys are zero, one, and other. You don’t need to reference these in the template, if you pass the count variable it will evaluate it and choose one for you.

For example:

And you would just need to pass your count variable for it to choose one of these based on the number:

• If the count is 0, it will choose zero, unless zero does not exist and then it will use other.
• 1 corresponds to one, and everything else will fall under others.

Other filters in combination

You can still use other filters in combination with t but you’ll use them *after***** you use the t filter. For example, to titlecase a translation:

Namespaced translations

You’ll use namespaced translations just as you would a translation without a namespace, but you’ll use a special way to access it in the message template. Make sure you have the same namespace across your locales if you use them so that the message template will be able to access all of the content in them. Here’s an example of using a namespaced translation in message template.

For a translation with a namespace of shipping:

To access the contents of the shipping translation in your message template you’ll reference the namespace before the key followed by a colon (”:”):

This can be helpful if you use the canceled key else where in your translations so that there isn’t a collision. For example, if you had a payments translation like this:

You would reference it with the payments namespace as well:

And if you had a translation that wasn’t namespaced, say the en translation, you would simply use the key alone. All together in a template, it would look like this:

Nested translations

You can create whatever JSON structure you need to hold your translations, sometimes those might be deeply nested. Given the following translation:

You can access the content with dot-syntax like this:

The same goes for namespaced translations. If the above translation was in a translation named services , you would do the following:

Rules for determining the translation used for a recipient

Locales have three levels of fallbacks:

1. Language + region
2. Language
3. Default locale (language OR language + region)

The message template will first try to find a translation that corresponds with a recipients specific language + region, like fr-BE for French-Belgian . If it doesn’t find one, it will fall back on looking for a translation for fr, since that’s the language code for the locale. And if it still can’t find that, it will fall back on the default locale, in the case of this example en.

Automate translation management with the Knock CLI

In addition to working with translations in the Knock dashboard, you can programmatically create and update translations using the Knock CLI or our Management API.

If you manage your own translation files within your application, you can automate the creation and management of Knock translations so that they always reflect the state of the translation files you keep in your application code.

The Knock CLI can also be used to commit changes and promote them to production, which means you can automate Knock translation management as part of your CI/CD workflow.

Translation files structure

When translations are pulled from Knock, they are stored in directories named by their locale codes. Their filename will be their locale code. Any namespaced translations will prepend the namespace to the filename, with . used as a separator.

If you're migrating your local translation files into Knock, you can arrange them using the file structure above and then push them into Knock with a single command using knock translation push --all. Each <locale>.json or <namespace>.<locale>.json file should follow the structure defined here.

You can learn more about automating translation management in the Knock CLI reference. Feel free to contact us if you have questions.

Supported locales

Below is a list of the available locales to choose from for your translations. If you need one added, contact us at support@knock.app.