Home
Guides
  1. DEVELOPER
  2. SceneGraph core concepts

SceneGraph localization

You can supply localized versions of the
strings and package graphical images used in a SceneGraph application
package. The SceneGraph application can then automatically insert the
localized versions of the strings and graphical images that you supply,
according to the current locale as set by the user.

You can also localize your application from your server using URL directives based on the current locale as set by
the user.

The application package localization features rely on the locales and locale
IDs currently supported by Roku. The list of these supported locales can be found in the description of the ifDeviceInfo GetCurrentLocale() method.

Localizing strings in the application package

For each string to be localized, provide localized translations of the string, in as many languages as you want
that are currently supported by Roku. You can provide localized strings
in either the TS or XLIFF XML localization file formats as supported by
Roku. The string localization files should be placed in the
pkg:/locale/ subdirectory for the supported locale. For example, if
you want to include a translations.ts localization file in the TS
format for Canadian French, place the file in the pkg:/locale/
subdirectory named for the locale ID fr_CA:

pkg:/locale/fr_CA/translations.ts

For strings defined in XML markup in a
<children> element, or <interface> element field strings,
the strings will be automatically translated by the SceneGraph
application, if translations of the string exist in the localization
files. If no translation file exists for the current locale, or no
translation of the string exists in the translation file, the original
string will be used.

All field values set in markup will be translated if the string value has a
corresponding entry in a translation file.
Roku best practices therefore strongly recommend initializing RSG field values
that need to be localized in the corresponding BrightScript Init() function.

For strings assigned using BrightScript in a
<script> element, you can use the
tr()
function to localize a string, if you have provided a translation of the
string in a translations.xml file in the XLIFF XML format in the
package directory pkg:/locale/locale_ID/ directory. The tr()
function is a global BrightScript utility function that looks for the
string in the translations.xml file, then finds the
corresponding string translation in the file for the current locale. To
use the tr() function to localize a specific source string:

tr(String source) as String

For example, to translate the string "hello world" in BrightScript:

m.greetinglabel.text = tr("hello world")

The tr() function will look for the
pkg:/locale/locale_ID/translations.xml file, and look in the file for
the "hello world" source string. If the source string exists in the
file, with a translated string, the translated string will be returned,
and assigned to the text field of the
Label node object m.greetinglabel. If no
translation file exists, or the source string and translated string does
not exist in the file, the original source string will be returned, and
assigned to the text field.

The tr() function also supports string substitutions. For example:

text = tr("Video will start in %1 seconds").Replace("%1", numSeconds.ToStr())

Localizing graphical images in the application package

For each graphical image to be localized,
provide each localized image in the pkg:/locale/ directory, in
as many languages as you want that are currently supported by Roku. Then
use the following format for the value of the uri field of the
Poster node:

pkg:/locale/images/localized_image

For example, to provide a localized version of myPoster.jpg, set the
Poster node uri field as follows:

<Poster uri="pkg:/locale/images/myPoster.jpg" />

This causes the application to search through the pkg:/locale
directory in the following order to find the localized graphical image.
The first graphical image of the specified name found in this search
sequence is returned to be rendered by the SceneGraph application.

  1. not localized
    pkg:/locale/images/image_name
  2. current locale
    pkg:/locale/locale_id/images/image_name
  3. default
    pkg:/locale/default/images/image_name
  4. US English
    pkg:/locale/en_US/images/image_name

If none of those files exist, the URL access will fail to return a file.

For example, if you want to have a localized version of a graphical
image for Canadian French, and a default image for all other languages,
place two versions of the image in the pkg:/locale directory as
follows:

pkg:/locale/fr_CA/images/image_name_canadian_french
pkg:/locale/default/images/image_name_default

In Brightscript in a <script> element, you can also use the getLocalizedAsset() method in ifLocalization to get a localized
graphical image.

For example:

localize = createObject("RoLocalization")
bannerposter = m.top.findNode("bannerPoster")
bannerposter.uri = localize.GetLocalizedAsset("images", "banner.png")

Is equivalent to:

bannerposter = m.top.findNode("bannerPoster")
bannerposter.uri = "pkg:/locale/images/banner.png"

TS file example

The following is an example of a
translations.ts file in the TS XML format placed in the
pkg:/locale/fr_CA directory to translate English to Canadian
French:

Example of a translations.ts file in the TS XML format

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE TS>
<TS version="2.0" language="fr_CA" sourcelanguage="en_US">
  <defaultcodec>UTF-8</defaultcodec>
  <context>
    <name>default</name>
    <message>
      <source>Hello</source>
      <translation>Bonjour</translation>
    </message>
    <message>
      <source>Goodbye</source>
      <translation>Au revoir</translation>
    </message>
    <message>
      <source>Christmas</source>
      <translation>Noel</translation>
    </message>
  </context>
</TS>

XLIFF file example

The following is an example of a
translations.xml file in the XLIFF XML format placed in the
pkg:/locale/fr_CA directory to translate English to Canadian
French:

Example of a translations.xml file in the XLIFF XML format

<?xml version="1.0" encoding="UTF-8"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
  <file source-language="en-US" target-language="fr-CA" >
    <body>
      <trans-unit id="0">
        <source>Hello</source>
        <target>Bonjour</target>
      </trans-unit>
      <trans-unit id="1">
        <source>Goodbye</source>
        <target>Au revoir</target>
      </trans-unit>
    </body>
  </file>
</xliff>

Localizing content

Apps can identify the region associated with a customer's Roku account to determine which content to display in the app UI. For example, apps can get the external IP address of a Roku device client-side, and return it back to the app's backend server. In the backend, the app can get the country ranges mapped to the IP address in order to determine which content to show to the customer and allow streaming. See App localization for how publishers should consider localization in the development, distribution, engagement, and monetization of their apps

Updated about 2 months ago

Did this page help you?