Embedded Workbook Localization

Localization allows workbook editors to translate workbook text to other locales. Translations are managed per-workbook and are available when viewing embedded workbooks and workbook previews.  

This article will show you how to translate your workbook text and apply your translations to embeds and previews.

Summary of Content

Requirements
Supported Languages and Locales
Create a Workbook Translation
Apply an Existing Translation to an Embed or Preview
Current Limitations
Related Resources

Requirements

• To add and/or edit translations, you must have Can Edit access to the individual workbook.
• Translated versions of a workbook can be viewed by anyone with an embed or preview workbook URL and a valid locale definition.
  
  

Supported Languages and Locales

The following languages are supported:

• Brazilian Portuguese (pt-br)
• English (en) default
• French (fr)
• French Canadian (fr-ca)
  
• German (de)
• Italian (it)
• Polish (pl)
• Portuguese (pt)
• Russian (ru)
• Spanish (es)
• Thai (th)
• Japanese (ja)
  

Create a Workbook Translation

Translations are managed via the MANAGE LOCALES panel, accessible from your workbook’s  settings menu.

1. Open the workbook.
2. Click the gear icon (), located in the workbook’s left sidebar, to open your workbook’s settings panel. 
3. Click Manage locales.
   
   This will open the MANAGE LOCALES panel.
4. To add a new language, click the panel’s plus icon (+).
   
   
5. Select a locale from the popup menu.
   Note: This selection determines translation of all standard Sigma text (e.g. menu labels, modal text, etc). It does not translate custom text.
   
   
6. [optional] Click the eye icon () to open a workbook preview using the translation. 
7. To begin adding your own translations, click the locale’s download icon.
   This will download a .json file containing all custom text contained in the workbook.
   
   
8. Open the downloaded file.
9. The .json file contains a list of key-value pairs.
   Update the “values” to the appropriate translations.
   Important: Do not edit any of the “keys”.
   
   Important:
   - Markdown is used for rich text
   - Dynamic text is represented like this → [={formula-id}]
   
10. After editing and saving your file, return to Sigma. 
11. Click your locale’s upload icon, and select your updated .json file.
    

Now what?

• Click the eye icon () to open a workbook preview with translated text.
• Add the locale to a workbook preview or embed URL, to view it in its translated state. See how
• Important: Each time you publish text changes to your workbook, you should download and re-upload the locale’s .json file with any new translations. 
• Existing text and translations will persist when the file is downloaded.
• Removed text will automatically be removed from the downloaded file, along with its translation.
• New text will be added at the bottom of the file, awaiting translation.

Apply an Existing Translation to an Embed or Preview

Translations are applied to previews and embeds via a URL parameter: :lng.

1. Identify the locale.
   This can be identified by the file name of the associated .json file.
   Example: The French Canadian locale is fr-ca.
   
   
2. Add :lng=<your-locale> to the end of the workbook’s preview or embed URL.
   Note: In the example above, the URL is passed two parameters (:embed and :lng).

Current Limitations

• Auto-generated data element names are not included in the Sigma generated .json file. Please manually name all data elements prior to defining your custom text translations.
• Some components and labels do not support translations yet. 
• Explore mode is not yet supported.
• Number and date formats are not supported.
  
  

Related Resources

Workbook Embedding: An Overview