written by Marcelo Viana
10 minutes reading
With the emergence of the USERCULTURE measure, the possibility of including measures in several visual and shape properties, and the addition of field parameters, creating multilingual reports has become a simpler task.
In mid-2023, Ted Pattinson, Principal Program Manager at Microsoft, published new guidelines on GitHub for creating these reports, using a tool called Translations Builder, which can be installed through this Link
In this article, I will show how Translations Builder can help us with the implementation of translations in reports, following the best practices and concepts defined by Ted Pattinson in his Article. TI will also bring practical examples of the tool in action and some tips based on the experience of those who have already used it in several reports.
In Power BI, there are three types of translation that can be applied to a report, each requiring a specific approach. Translations Builder is capable of performing two of them:
1. Translation of semantic model metadata; 2. Translation of free-text values such as visual titles, headers, or any text input that accepts a measure as its value.
The third type, data translation, will not be covered in this article, as it is performed using field parameters and cannot be done through the tool.
In most cases, the first two types of translation are already sufficient to allow multicultural audiences to access and use a report easily. Next, we will see how these types are handled by the tool.
The Caption property is the most relevant for users who view reports, as it defines the display name of the object. For example, in a Power BI file with a measure called “Total Cost,” the Caption property stores exactly this value — “Total Cost.”
Although translating the** Caption is usually sufficient for report consumers, the Description and Display Folder** properties can also be useful, especially for authors who create and edit reports in the Power BI service.
To enable these translations in Power BI, we will use Translations Builder, which, after installation, will be available in the “External Tools” menu.
Below, we present the tool’s interface:
In this example, I am using a table with pets available for adoption (available at em Adoptable Pets - Catalog).
Observe que, na coluna “Property”, aparecem apenas valores do tipo “Caption” para as colunas e para a tabela. Isso acontece porque não adicionei nenhuma descrição nem criei pastas para organização.
Also note that the “Default Language” field is set to English [en-US]. This language is defined at the time the file is created, according to the language and location settings of your Power BI Desktop — this point is very important and will be detailed later.
Each row displayed in the Translations Builder table represents a dataset object that *can be translated via metadata. These objects are identified by the “Object Type” column (Table for table names, Column for column names, and Measure for measure names) and by the “Name” column, which shows the original name of the object.
Next, I will add the languages Portuguese (Brazil) and Spanish (Latin America) to my file by clicking the “Add Language” button:
After adding the languages, new columns will be displayed in the tool — one for each included language.
There are three ways to assign translations to dataset objects:
1. Manual entry (direct input); 2. Using an exported Excel file; 3. Integration with the Azure Translator Service.
In this example, I will use the first method, manually filling in the cells of the column corresponding to the Portuguese language:
For the Spanish language, I will use the second method. By generating exports, we allow more people to collaborate in the translation process. In contexts where the developer needs to focus efforts on other tasks — or does not master the target language — relying on native business users can be an efficient approach.
To do this, Translations Builder introduces the concept of a translation sheet, a CSV file exported directly from the tool. This file can be sent to a human translator, who makes the necessary adjustments and returns it updated. It can then be imported to integrate the revised translations directly into the dataset.
This method is especially useful when there are specialists or business users available to contribute more accurate and contextualized translations.
To use it, you must first define the export and import directory. This configuration can be done in “Dataset Connection” > “Configure Settings…”:
With the directories properly configured, in the *“Export/Import Translations” submenu, I select the desired language from the menu and click *“Export Translations Sheet”**:
Here is the file:
After filling in the fields in column E and saving the file in the import directory, the result can be viewed in Translations Builder:
In the third translation method, Translations Builder generates automatic translations through API calls to the Azure Translator Service, an endpoint offered by Azure Cognitive Services. This Web API allows you to automate the enumeration of dataset objects, translating them from the default language to secondary languages.
Although the result of using Azure Translator Service is not demonstrated in this article, I will show the steps required to enable it. To do so, simply enter the service access key and the location where it is hosted in the external tool settings:
After entering the data, a new option will be displayed in the main menu. Simply select the desired language and click “Generate Translations” to generate the translations:
Now that we understand the three methods for translating semantic model metadata, let’s understand how Power BI manages these translations and makes them visible to users.
Understanding this process is essential, as it directly influences how reports are developed and serves as the basis for the second type of translation addressed in this article: the translation of values based on free-text, such as visual titles and headers in general.
Both metadata translations and free-text translations are applied at the Power BI semantic model level — not at the report layout level. Power BI Desktop and the Power BI service do not support storing or loading translations of text values that are inserted directly into the layout.
For example, a text contained in a measure is stored in the semantic model and can be translated. A text inserted into a text box, however, is in the report layout and therefore cannot be translated this way.
When a report is loaded in the Power BI service, it is interpreted based on the user context, which includes language and geographic region — usually defined by country. This combination is tracked through an identifier called culture name.
The culture name is usually composed of two elements:
1. the lowercase language identifier; 2. followed by the uppercase locale identifier, separated by a hyphen (for example: pt-BR).
This value can be determined by the language and locale settings of the operating system, browser, or directly in the Power BI service preferences. The semantic model uses this information to decide which previously configured translation version will be displayed to the user.
Below are some examples of culture names:
Source: Microsoft Learn
In the demo file created for this article, I added a table visual in Power BI Desktop, displaying the columns from the table of pets available for adoption.
In addition, I inserted five card visuals to present the measures: Total Pets, Total Dogs, Total Cats, Total Birds, and Others.
It is important to note that in Power BI Desktop, information will always be displayed in the original language, as defined in the Dataset Properties > Default Language menu of Translations Builder. This language is determined at the time the file is created in Power BI Desktop, according to the language and country settings defined within the tool itself:
My computer and browser are configured for Portuguese (Brazil). When publishing the file, it is possible to observe that the column and measure names are displayed in Portuguese, as previously configured in Translations Builder.
It is possible to force the display in a specific language using the URL parameter "language=".
For example, if I want to view the metadata in English, I can add the following at the end of the URL: "&language=en-US":
The same procedure can be applied to all languages (culture names) added to the dataset through Translations Builder.
In our demo, we also included Spanish (Latin America), which can be accessed by adding the following parameter to the URL: “&language=es-419”
The second type of translation that can be performed with the help of Translations Builder is the translation of any text input, as long as that text is used in a visual or shape that accepts measures instead of static values.
For demonstration purposes, I will translate the report page header and the title of a chart that will be inserted on the page. To enable this type of translation, we will add labels in Translations Builder. To do this, press Ctrl+A on the tool’s main screen. The labels to be added are:
1. "Pets Available for Adoption" (for the page title) 2. "Pets Distribution per Size" (for the chart title)
After clicking “Add Labels”, they will appear in the table along with the other fields translated via metadata. Then, just add the translations as we did before and press Ctrl+L.
This shortcut creates a table called “Translated Localized Labels” directly in the semantic model of your Power BI Desktop file.
Translations Builder will automatically generate, within this table, measures corresponding to the labels and translations entered.
The structure of these measures is composed of a SWITCH expression combined with the USERCULTURE function, simulating the behavior that the semantic model applies to metadata.
Below is an example of a measure generated for the page title:
Pets Available for Adoption Label = SWITCH( USERCULTURE(), "pt-BR", "Animais de Estimação Disponíveis para Adoção", "es-419", "Mascotas Disponibles para Adopción", "Pets Available for Adoption" )
The USERCULTURE measure returns the culture name of the user accessing the report in the Power BI service, in the same format described earlier in this article.
Note that the else of the measure is reserved for the default language associated with the semantic model — in my case, English.
These measures must be bound to the display location (such as visual titles or text boxes that accept measures), and their translations will work in the same way as metadata translations.
Below you can see how the text display in the report header was configured and how the information is presented in English in the local environment:
When publishing the file to the Power BI service, both headers are displayed in Portuguese.
In addition, note that the chart legend and the X-axis title are also translated — in this case, through metadata:
The default language of the semantic model is defined by the language and locale settings of Power BI Desktop at the time the file is created.
As seen earlier, this language is essential, as it will be used whenever the user’s culture name does not match any of the secondary languages.
For example, if a user with a French regional configuration (fr-FR) accesses the demo file in this article, the displayed language will be English, which is the default language of the model.
If you identify that the need for multiple languages may arise in the future, it is important to align this with stakeholders and define an appropriate default language before creating the file.
As mentioned, only semantic model data can be translated. Therefore, elements stored at the layout level, such as page names, are not automatically translated.
To work around this limitation, it is recommended to use buttons with translated text to navigate between report pages.
In addition, in some cases, users may want to manually change the display language, even if they are associated with a specific culture name.
For example, a Brazilian user (pt-BR) who needs to present the report to an American audience may want to display it in English.
To facilitate this change intuitively, you can add buttons on the report’s home page that redirect the user to a URL with the "language=" parameter already defined.
This way, the user does not need to manually edit the URL — just one click to switch the display language.
To conclude this article, it is important to highlight some limitations related to the use of translations in Power BI reports.
Applying translations in the semantic model is restricted to workspaces associated with dedicated Power BI Premium capacities. Reports stored in shared capacities do not correctly load the configured translations.
The simplest way to identify whether a workspace is Premium is to check if there is a diamond icon next to the workspace name.
Another limitation of Translations Builder is that it only allows translating semantic model objects. Elements stored at the report level — such as text boxes and tab names — do not support translation.
In addition, the tool does not perform data translation itself. However, Ted Pattinson’s article presents best practices for dealing with this type of need, should data translation be a requirement.
