Localization Guide
chevron down
back search icon cancel search
 
 

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.

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

With these additional languages added in Fitbit OS 4.2:

  • Russian - ru-RU
  • Portuguese (Brazillian) - pt-BR
  • Romanian - ro-RO
  • Czech - cs-CZ
  • Polish - pl-PL
  • Indonesian (Bahasa) - id-ID

Fitbit OS 5.2 added support for:

  • Norwegian - nb-NO

    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    ru-RU.po
pt-BR.po    ro-RO.po    cs-CZ.po    pl-PL.po    id-ID.po    nb-NO.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    ru-RU.po
pt-BR.po    ro-RO.po    cs-CZ.po    pl-PL.po    id-ID.po    nb-NO.po

./resources:
icon.png     index.view    styles.css    widget.defs

./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    ru-RU.po
pt-BR.po    ro-RO.po    cs-CZ.po    pl-PL.po    id-ID.po    nb-NO.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.

SVG Files

If you need to use localizations within your SVG 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.

previous
Glossary Guide
Migration Guide
next