Go to Slack

Localiz(s)ing your Slack apps

The rundown
Read this if:You're still experimenting, prototyping, and exploring.
Read next:Design guidelines for Slack apps

The makeup of your audience may require your app to become a polyglot. 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.

This guide will show you some ways localization can work in apps, and outline how to determine which locale to adjust for.


What to localize

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

Localization is a great way to tailor your app for different audiences dynamically—read our interaction and user experience design guidelines to understand how to wield this tool responsibly.