Manage workbook localization

Localization allows workbook editors to translate custom workbook text into other languages. Translations apply to workbook previews and embed views.

Administrators can also create organization-level translations that apply across all workbooks in a Sigma organization. For more information about organization-level translation files managed by your administrator, see Manage organization translation files.

Requirements

To manage workbook translations, you must be granted Can edit workbook permission.

📘

Any user with a workbook preview or embed view URL and a valid locale definition can view a translated workbook.

Supported languages and locales

Sigma supports the following languages and locales:

Create a workbook translation

Manage locales and translations for your workbook using the Manage locales panel, accessible from your workbook’s settings menu.

1. Open the workbook in Edit mode.

2. Click the settings icon (), located in the workbook’s left sidebar, to open your workbook’s settings panel.

3. Click Manage locales.

4. To add a new language, click the plus icon (+) next to Available locales.

5. Select a language from the dropdown menu.

📘

Completing this step to create a locale for a workbook enables translation of all standard Sigma text (for example, menu labels, modal text, etc). To translate custom text in the workbook, complete the rest of this procedure.

6. To add translations for custom text in your workbook, click the more icon (), and download the json file.

7. Open the downloaded file.

8. The .json file contains a list of key-value pairs.
   Update the values to the appropriate translations.

   🚩

   Do not edit any of the keys.

   

9. Edit and save your file. Do not change the filename.

10. Return to Sigma. Click Upload, and select your updated .json file.

11. Click the preview icon () to open a workbook preview with translated text.

Update a workbook translation

Each time you publish text changes to your workbook, you need to download and re-upload the locale’s .json file with new translations for any new or changed text strings. Newly added strings appear at the bottom of the json file.

If an administrator has created an organization-wide translation file for the language, you'll need to choose between downloading just the untranslated strings or downloading all strings.

Add a custom translation for a language

You can maintain multiple unique translations for a given language. Adding a custom translation for a language allows you to translate the strings in your workbook differently for different consumers of embedded dashboards, for example. You can also inherit custom translations from organization-level files created by your administrator.

1. Open the workbook in Edit mode.

2. Click the settings icon (), located in the workbook’s left sidebar, to open your workbook’s settings panel.

3. Click Manage locales.

4. Click the plus icon (+) next to Available locales.

5. In the dropdown menu, select Add custom translations.

6. Type a name for your custom translation file.

   🚩

   If you want to inherit a custom set of organization-level translations defined by your admin for this language, you must use the same name here as the one your admin used when they created the organization-level translation file. Ask your admin for the name of their file.

7. Set the Base language to specify the language to use for all standard Sigma text (for example, menu labels, modal text, etc).

8. Click Add.

9. In the list of available locales, find the custom language variant you just added.

   📘

   If an organization-level language variant exists and you used the same name for the custom language variant file, the organization-level file displays in gray.

10. To add translations for custom text in your workbook, click the more icon (), and download the json file.

7. Open the downloaded file.

8. The .json file contains a list of key-value pairs.
   Update the values to the appropriate translations.

   🚩

   Do not edit any of the keys.

   

9. Edit and save your file. Do not change the filename.

10. Return to Sigma. Click Upload, and select your updated .json file.

11. Click the preview icon () to open a workbook preview with translated text.

Use markdown and dynamic text in a translation file

You can use Markdown and dynamic text in your json values to support rich text.

Use this syntax to produce dynamic text as part of a value: [={formula-id}]

Use Markdown syntax for other rich text:

Apply locales and translations to embeds or previews

To apply a locale to an embed or preview, append the embed or workbook preview URL with :lng=<your-locale>. Applying a locale translates the standard Sigma text, such as menu labels and modal text, into the language associated with the locale. If a translation file is defined for that locale, applying the locale also translates the custom text in the workbook with any defined translations.

If you are applying a custom translation variant of a language, also append with :lng_variant=<variant+name>. Use URL encoding for any special characters in the name.

Example embed API code:

// NOTE: Localization values are case sensitive
searchParams += '&:lng=fr-ca';

Example embed API code for a custom translation variant:

// NOTE: Localization values are case sensitive
searchParams += '&:lng=it&:lng_variant=Custom+Italian';

Example embed URL:

https://app.sigmacomputing.com/my-company/workbook/My-Workbook-2PG8oM9uFxNLyzxAukJfBrL?:embed=true&:lng=fr-ca

Example embed URL for a custom translation variant:

https://app.sigmacomputing.com/my-company/workbook/My-Workbook-2PG8oM9uFxNLyzxAukJfBrL?:embed=true&:lng=it&:lng_variant=Custom+Italian

💡

A translation file is not required to apply a locale.

Even if no translation file has been defined, you can use the parameters above to apply a locale to an embed or preview in order to display the standard Sigma text, such as menu labels and modal text, in a different language.

For example, if your workbook is written in Japanese and the source data it displays is also in Japanese, you can apply the &:lng=ja parameter so that the workbook's menu labels and other standard text also display in Japanese.

Current limitations

• Auto-generated data element names (for example, Sum of Cost by Year of Date) are not included in the Sigma generated .json file. Manually name all data elements prior to defining your translations.
• Explore mode is not supported.
• Number and date formats are not supported.