Links

Adding localization to the dashboard

In this subpage, we will cover how to set up localization for your dashboard.
This page is a work in progress. It will be updated as the software evolves.

Overview

This is the second part of our guide to building a Custom Dashboard. This part continues work on the dashboard we built in part one: Creating a Custom Dashboard, but further shows how to handle localization in a custom dashboard.

Localization

If you want the dashboard to be available in different languages, you can use the existing localizations from Umbraco or register your own localizations. The localizations are written as a key-value pair pattern.
To register localizations to a language, you need to add a new manifest to the Extension API. The manifest can be added through the umbraco-package.json file like this:
umbraco-package.json
{
...
"extensions": [
{
"type": "localization",
"alias": "MyPackage.Localize.DaDK",
"name": "Danish",
"meta": {
"culture": "da-dk"
},
"js": "/App_Plugins/MyPackage/Localization/da-dk.js"
}
]
}
Tip: If you do not have many translations, you can also choose to include the localizations directly in the meta-object. Read more about translations in the Localization article.
Create two new files en-us.js and da-dk.js.
Add the following code to en-us.js
en-us.js
1
export default {
2
welcomeDashboard: {
3
heading: "Welcome",
4
bodytext: "This is the Backoffice. From here, you can modify the content, media, and settings of your website.",
5
copyright: "© Sample Company 20XX",
6
}
7
};
Add the following code to da-dk.js
da-dk.js
1
export default {
2
welcomeDashboard: {
3
heading: "Velkommen",
4
bodytext: "Dette er Backoffice. Herfra kan du ændre indholdet, medierne og indstillingerne på din hjemmeside.",
5
copyright: "© Sample Selskab 20XX",
6
}
7
};
Now let's update our umbraco-package.json extensions object to register our new localization file:
umbraco-package.json
{
...
"extensions": [
{...},
{
"type": "localization",
"alias": "MyPackage.Localize.EnUS",
"name": "English (United States)",
"meta": {
"culture": "en-us"
},
"js": "/App_Plugins/WelcomeDashboard/Localization/en-us.js"
},
{
"type": "localization",
"alias": "MyPackage.Localize.DaDK",
"name": "Danish",
"meta": {
"culture": "da-dk"
},
"js": "/App_Plugins/WelcomeDashboard/Localization/da-dk.js"
}
]
}
See the entire file: umbraco-package.json
umbraco-package.json
1
{
2
"$schema": "../../umbraco-package-schema.json",
3
"name": "My.WelcomePackage",
4
"version": "0.1.0",
5
"extensions": [
6
{
7
"type": "dashboard",
8
"alias": "my.welcome.dashboard",
9
"name": "My Welcome Dashboard",
10
"js": "/App_Plugins/WelcomeDashboard/dashboard.js",
11
"elementName": "my-welcome-dashboard",
12
"weight": -1,
13
"meta": {
14
"label": "Welcome Dashboard",
15
"pathname": "welcome-dashboard"
16
},
17
"conditions": [
18
{
19
"alias": "Umb.Condition.SectionAlias",
20
"match": "Umb.Section.Content"
21
}
22
]
23
},
24
{
25
"type": "localization",
26
"alias": "MyPackage.Localize.EnUS",
27
"name": "English (United States)",
28
"meta": {
29
"culture": "en-us"
30
},
31
"js": "/App_Plugins/WelcomeDashboard/Localization/en-us.js"
32
},
33
{
34
"type": "localization",
35
"alias": "MyPackage.Localize.DaDK",
36
"name": "Danish",
37
"meta": {
38
"culture": "da-dk"
39
},
40
"js": "/App_Plugins/WelcomeDashboard/Localization/da-dk.js"
41
}
42
]
43
}
It is currently not an option to localize the dashboard label. This is a work in progress.
We can use the umb-localize element to get the localizations out, which takes a key property in.
Let's start using the localizations:
welcome-dashboard.element.ts
render() {
return html`
<h1>
<umb-localize key="welcomeDashboard_heading">Welcome</umb-localize>
Dashboard
</h1>
<div>
<p>
<umb-localize key="welcomeDashboard_bodytext">
This is the Backoffice. From here, you can modify the content,
media, and settings of your website.
</umb-localize>
</p>
<p>
<umb-localize key="welcomeDashboard_copyright">
© Sample Company 20XX
</umb-localize>
</p>
</div>
`;
}
See the entire file: welcome-dashboard.element.ts
welcome-dashboard.element.ts
1
import { LitElement, css, html, customElement } from "@umbraco-cms/backoffice/external/lit";
2
import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
3
4
@customElement("my-welcome-dashboard")
5
export class MyWelcomeDashboardElement extends UmbElementMixin(LitElement) {
6
7
render() {
8
return html`
9
<h1>
10
<umb-localize key="welcomeDashboard_heading">Welcome</umb-localize>
11
Dashboard
12
</h1>
13
<div>
14
<p>
15
<umb-localize key="welcomeDashboard_bodytext">
16
This is the Backoffice. From here, you can modify the content,
17
media, and settings of your website.
18
</umb-localize>
19
</p>
20
<p>
21
<umb-localize key="welcomeDashboard_copyright">
22
© Sample Company 20XX
23
</umb-localize>
24
</p>
25
</div>
26
`;
27
}
28
29
static styles = [
30
css`
31
:host {
32
display: block;
33
padding: 24px;
34
}
35
`,
36
];
37
}
38
39
declare global {
40
interface HTMLElementTagNameMap {
41
"my-welcome-dashboard": MyWelcomeDashboardElement;
42
}
43
}
The dashboard's text will appear depending on the user's language. If the user's language is Danish, the dashboard will use the text from our da-dk file. If the user's language is English, the dashboard will use the text from our en-us file.
The text between the open and close tags of umb-localize is the fallback value in case the key can't be found or doesn't exist.
This is how our dashboard should now look like:
Dashboard if the user's language is English / Fallback
Dashboard if the user's language is Danish

Going Further

With the part completed, you should have a dashboard welcoming your users' language.
In the next part, we will look into how to add more functionality to the dashboard using some of the Contexts that Umbraco offers.