Localization Guide
chevron down
 

Localization Guide

Overview

This guide explains how developers can translate their app, companion, and settings, into different languages based upon the current user's locale, using the i18n API added in SDK 3.1.

Traditionally developers had to store strings within their JavaScript code, which negatively impacted memory usage, but the new API dynamically loads the correct strings at runtime, removing the overhead.

Supported Locales

The Fitbit OS firmware supports the following languages:

  • German - de-DE
  • English (US) - en-US
  • Spanish - es-ES
  • French - fr-FR
  • Italian - it-IT
  • Japanese - ja-JP
  • Korean - ko-KR
  • Dutch - nl-NL
  • Swedish - sv-SE
  • Chinese (simplified) - zh-CN
  • Chinese (traditional) - zh-TW

Files and Folders

Translated strings need to be provided in PO File Format.

Here's a sample en-US.po file:

msgid "hello"
msgstr "Hello!"

msgid "goodbye"
msgstr "Goodbye!"

Here's a sample fr-FR.po file:

msgid "hello"
msgstr "Bonjour!"

msgid "goodbye"
msgstr "Au revoir!"

You should create one .po file for each language you wish to support. Then place the .po files within an i18n folder in the /app, /companion, or /settings/ folders. There is no common folder location for localized strings, so you may need to duplicate some strings.

./app:
i18n     index.js

./app/i18n:
de-DE.po    en-US.po    es-ES.po    fr-FR.po    it-IT.po    ja-JP.po
ko-KR.po    nl-NL.po    sv-SE.po    zh-CN.po    zh-TW.po

./companion:
i18n     index.js

./companion/i18n:
de-DE.po    en-US.po    es-ES.po    fr-FR.po    it-IT.po    ja-JP.po
ko-KR.po    nl-NL.po    sv-SE.po    zh-CN.po    zh-TW.po

./resources:
icon.png     index.gui    styles.css    widgets.gui

./settings:
i18n      index.jsx

./settings/i18n:
de-DE.po    en-US.po    es-ES.po    fr-FR.po    it-IT.po    ja-JP.po
ko-KR.po    nl-NL.po    sv-SE.po    zh-CN.po    zh-TW.po

If a required .po file is not found, the system will automatically fallback to en-US.po, or the defaultLanguage specified within the package.json.

JavaScript Code

Once you've created your language files, you can import the i18n module and use the gettext() function to retrieve the localized strings.

import { gettext } from "i18n";

console.log(gettext("hello"));
// en-US: Hello!
// fr-FR: Bonjour!

If a msgid is not found within the selected language file, the msgid itself is returned.

GUI Files

If you need to use localizations within your .gui files, you must create the i18n folder within the /app folder, then reference each msgid prefixed with an underscore.

<svg>
  <text>_hello</text>
</svg>

Localization in Action

If you're interested in using localization in your application, why not check out the i18n sample application, or the i18n reference documentation.