Translating Dashboards with Project Translations

Project translations let you define a custom dictionary of translated text for a project, so that the text you configure on your dashboards appears in the language selected by the user.

While the Changing the Default Language page covers translating the Squirro interface itself, project translations cover the text you add to your own dashboards. This is useful when you build a project in one language and want the same dashboards to display in another language without maintaining a separate copy for each language.

Project translations apply only to the static text you enter when configuring a dashboard, such as widget titles and labels. They do not translate the content that comes from your indexed data. For example, the title of a results widget can be translated, but the item titles, item summaries, search results, and facet values shown inside that widget remain in the language of the underlying data.

How Project Translations Work

Each project holds a list of translation entries. Every entry has a key and one value per language. You reference a key in your dashboard text, and Squirro replaces the reference with the value for the language the user has selected.

For example, an entry might define the key :remote_work with the value Remote work in English and Telearbeit in German. When you use that key in a widget title, a user viewing the dashboard in German sees Telearbeit, while a user viewing it in English sees Remote work.

Prerequisites

Before you can use project translations, an administrator must configure the following server settings using the Configuration Service:

• frontend.userapp.translate-widget-values

  Turns on project translations. This setting is off by default, so set it to true to use the feature.

• frontend.userapp.languages

  The languages available to the user, as a comma-separated list of ISO 639-1 language codes. Each language you list becomes a column in the project translations editor and an option in the language selector.

Squirro ships its interface translated for English, German, French, and Italian. Project translations let you add translations for your own dashboard text in these same languages, so your dashboards are fully translated when a user switches language. For instructions on setting the default and selectable languages, see the Changing the Default Language page.

Notes for administrators

• The frontend.userapp.translate-widget-values setting requires server-level Administrator access.

• If no languages are configured, the project translations editor has no columns and cannot store translations.

Managing Translations in the UI

You manage a project translation dictionary from the Project Translations screen. To open it, go to the Setup space, select the Visualization tab, and select Project Translations in the left sidebar.

Each row represents one translation entry and contains:

• Key

  The identifier you use to reference the entry from your dashboard text. Follow these guidelines when naming a key:

  • Start every key with a single colon, for example :remote_work.

  • Use letters, numbers, and underscores only. Replace spaces with underscores and avoid other special characters, including additional colons.

  • Choose a distinctive, project-specific name. Keys share a namespace with Squirro’s built-in interface labels, so a generic key such as :cancel can override interface text.

  • Enter the phrase you want to display, such as Remote work, in the language columns rather than in the key.

• One column per language

  The translated value for each language configured in frontend.userapp.languages. Each column is labeled with its ISO 639-1 language code, for example EN, DE, FR, and IT. For the :remote_work key, enter Remote work for EN, Telearbeit for DE, Télétravail for FR, and Telelavoro for IT.

To add a translation:

1. Select the + icon in the top right to add a row.

2. Enter a key and the translated value for each language.

3. Select Save.

The keys must be unique within a project. If two entries share the same key, Squirro does not save the dictionary and briefly displays a message listing the duplicated keys. Because this message disappears after a few seconds, confirm that your changes are saved and make each key unique if the dictionary does not save.

Referencing Translations in Dashboards

To display a translated value, reference its key in the dashboard text you configure, such as a widget title, by prefixing the key with a dollar sign. For a key of :remote_work, the reference is $:remote_work.

The dollar sign marks the text as a translation reference. It lets Squirro tell a reference apart from an ordinary colon in your text and lets you place a reference alongside other characters. For example, the title $:remote_work 2024 displays as Remote work 2024 in English and Telearbeit 2024 in German, where only the reference is replaced and 2024 is left unchanged.

Translations are applied when a dashboard is viewed. While you edit a dashboard, references are shown as you entered them so that you can see and change the keys.

If an entry is missing a value for the language the user has selected, the text does not translate as intended. To avoid missing or untranslated text, provide a value for every language in each entry.

Switching the Display Language

Project translations take effect when a user selects a language from the language selector in the top navigation bar. The available languages are those an administrator configures for the project.

Managing Translations Programmatically

You can also manage project translations with the SquirroClient Python SDK. The SDK provides methods to retrieve, replace, and update the translation set for a project, where each translation is a dictionary with a key and one entry per language code.

For the full list of methods and their parameters, see the APIs by Topic page.

Importing and Exporting Translations

Project translations are included when you import or export a project, so the dictionary moves with the project between environments. For instructions on importing and exporting projects, see the Project Export & Import page.