It is likely that most of the channels you’ve used on your Roku player use English in their user interfaces. However, support for other languages on Roku devices has been steadily improving. Therefore, as a channel developer, it is increasingly important that you know how to build your channels to support a variety of languages. Currently, Roku supports English of course, as well as French (as of firmware version 4.6) and Spanish and German (added in firmware version 4.8.) This article discusses the key steps needed to create multilanguage channels.
Locales on Roku
A localized channel typically contains language or culture specific text and images (such as locally relevant icons.) A localized channel may further contain audio files in the local language. BrightScript makes it easy to include any language specific assets you like as part of your channel. If packaged using the techniques described in this article, the correct assets are loaded and rendered based on the Roku device’s language setting. Furthermore, you can publish one package to the Channel Store that supports all of your languages, instead of one package per language.
Roku channels expect to find locale specific assets in the locale directory hierarchy, similar to the one shown below:
Under the locale folder, you define subfolders for each of the languages supported by your channel. In this example, the channel supports English and Spanish. Accordingly, there is an en_US folder for English and an es_ES folder for Spanish. Each of these locale folders can then contain whatever additional subfolders and files are needed to hold all of the language specific channel assets. For example, icons containing Spanish text could go in an es_ES/images subfolder, or Spanish audio files could go in a folder named es_ES/audio. When your channel runs and makes requests for localized resources, the Roku device will look in the locale folder hierarchy associated with the current language setting on the device. Thus, if the device is configured for Spanish, resource API calls will look in folders under the pkg:/locale/es_ES path. We will take a look at the various localization APIs shortly.
Your channel can also define a default locale folder under locale/default. This folder can be used just like a locale folder, except that it is used to store assets that are common to all locales supported by the channel. For example, if you have a logo or other branding that is common across all languages, those assets can be kept in the default locale folder structure.
Two other files that can be in a locale hierarchy are manifest and translations.xml. The manifest file plays the same role as the main manifest file, specifying the channel title, subtitle, focus and side logos, and the like. The difference is that the values in the locale specific manifest files are used to define these properties for the corresponding language. It is also important to keep in mind that manifest files are additive. The Roku device will parse the top level manifest file, and then parse the locale specific manifest, adding properties from the latter to those found in the top level file. Therefore manifest properties that are locale independent, such as version numbers, should be stored in the top level manifest file.
The second file, translations.xml, is an XLIFF compliant localization file that contains translations of text strings for the associated locale. As an example, this is what a German translations.xml file might look like:
Each element contains a source and a target. The source string is referenced in your BrightScript code to identify a localized string to load into your channel. The target string is the localized version of the source string. The source string is typically the default locale (such as English) version of the string in question. The source is mapped to the target using the BrightScript global function tr():
tr(String source) as String
BrightScript will look up the source string in the translations.xml file that corresponds to the Roku device’s current language settings, and return the associated target string. For example, if the device’s language is set to German, the following code would return the string “Verlassen Video”:
REM This call will return “Verlassen Video” str = tr(“Exit Video”)
Loading Non-String Resources in a Localized Channel
Previously we saw how localized strings are loaded into a channel using the tr() command. But what about other resources such as images? For this there is a BrightScript component called roLocalization. The main method defined by this component for loading resources is GetLocalizedAsset:
GetLocalizedAsset(String dirName, String fileName) as String
This function takes two string arguments. The first is the name of the directory in which the file specified by the second argument is located. The directory name is relative to the corresponding locale folder. As an example, let’s assume that the Roku device language is set to French. Further, let’s assume that you want to load an image file called playbutton.png located in your locale/fr_CA/images folder. Since the Roku device knows that the current language is set to French, you don’t need to specify locale/fr_CA as part of the directory name. The device knows to look there for the resource. So you would call GetLocalizedAsset as follows:
path_to_image = GetLocalizedAsset(“images”, “playbutton.png”)
After this call, path_to_image will contain the full path to the image, specifically:
Your BrightScript code can then use this return value to load the image into any UI component. To make using GetLocalizedAsset easy, images or other assets in your channel should use the same file name for each locale version. In the previous example, each version of the image file should be named playbutton.png. This allows you to make one GetLocalizedAsset call to load the image independent of the Roku device language settings.
When searching for assets, GetLocalizedAsset first looks in the current locale folder structure. If the specified file is not found, the API will search the locale/default folder. If the file is not there, it looks next in the locale/en_US folder. If the asset is not found there, GetLocalizedAsset returns an empty string.
To help you dig deeper into Roku channel localization, I’ve updated the Channel Diner sample application from my last post. The diner now has three cuisines: Mexican, French, and good old classic American food. To see the various options, set your Roku device language to English, French, or Spanish and have fun!
Sample Localization Channel