Localiz(s)ing your Slack apps

When sticking to English (US) isn't sufficient, it's possible to provide localized app content.

Localization of Slack apps is a manual process—detect a locale and adjust display text to accommodate—but there are API methods to help you on your way.

Any piece of text that your app publishes directly to users can be localized — any text in messages or modals, for example. You can't localize pre-configured text in actions like slash commands or message actions — although you can respond to those actions in different languages. And it's currently not possible to localize your app's display name.

Knowing which language to display

There are two basic preferences for language that are visible to apps.

The first is the chosen language of the conversation that the app is currently operating in. The second is the display language of an individual user of the app.

It's ultimately up to you to decide how to combine these two possible language preferences into a chosen display text. In most cases, a mixture of different strategies for different contexts will be appropriate.

Picking the right language for each context

A localized app should use the channel's locale for channel-published content. The app can then optionally use an individual user's locale for content only visible to that specific user.

The goal should be to ensure that the most common language is chosen for the entire audience in each context.

Consider a task tracking app. The app publishes messages on a recurring schedule to a public channel that list all incomplete tasks for a project. Users can also interact both publicly and privately with the app to create and modify tasks.

Imagine that the public channel has a language locale of German, but an individual user has their own preferred language locale of French.

In this case, any content visible only to the French user would be published in French. Any content visible to the German channel would be published in German, even if the publishing of that content was triggered by the French user.

Retrieving locale preferences

There are multiple locations within Slack APIs where you can encounter a locale field.

Within the Web API, you can retrieve the locale of any type of conversation by using conversations.info. Set include_locale to true when making your API call, and you'll get back a locale field—a string containing an IETF language code such as en-US or de-DE.

You can also retrieve the preferred language of a user by using users.info with the same include_locale parameter as above. This will return a locale field in the same format.

If you use the Events API, you will also see a locale field for any user_change events you might receive.

Your app should check the conversation or user locale - via one of the methods listed above - every time the app wants to publish or update content.

Go beyond speaking tongues

Once you start retrieving locale preferences, you can customize your app's experience. Changing language to suit audience is the most common usage for this.

But apps could also customize cultural references to be appropriate for a specific region, culture, or language.

Apps could use this info to tailor interactivity too—a travel booking app that selected default departure airports based on locale could provide a much more rapid booking experience to users.