Add support for custom UI labels to the GUI whitelabel runtime system by hsato03 · Pull Request #13415 · apache/cloudstack

hsato03 · 2026-06-12T22:03:51Z

Description

The GUI whitelabel management system has been extended with the customLabelsPath parameter to allow customization of UI labels. This parameter accepts the path to a directory containing the label files, which must be named according to their language code (e.g., en.json for English).

If files are stored directly on the Management Servers, the base path is /usr/share/cloudstack-management/webapp/, so only the relative path needs to be specified. Alternatively, a full URL to the directory hosting the JSON files can be provided.

Note: The path or URL where the custom language files are located must be accessible by the user.

Types of changes

Breaking change (fix or feature that would cause existing functionality to change)
New feature (non-breaking change which adds functionality)
Bug fix (non-breaking change which fixes an issue)
Enhancement (improves an existing feature and functionality)
Cleanup (Code refactoring and cleanup, that may add test cases)
Build/CI
Test (unit or integration test code)

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Major
Minor

Bug Severity

Screenshots (if appropriate):

How Has This Been Tested?

I created the en.json file in the /usr/share/cloudstack-management/webapp/locales/custom_labels directory with the following content:

{
    "label.name": "Nome custom"
}

I created the theme specifying the directory where the en.json file was created:

(local) 👻 > create guitheme name="test" customlabelspath="locales/custom_labels"  css='.layout.ant-layout .header {background: orange;}'
{
  "guiThemes": {
    "created": "2026-06-12T21:38:03+0000",
    "css": ".layout.ant-layout .header {background: orange;}",
    "customlabelspath": "locales/custom_labels",
    "id": "69e6e38b-8a56-442c-9ff4-141138a37b2f",
    "ispublic": true,
    "name": "test",
    "recursivedomains": false
  }
}

Navigating through the ACS GUI, I verified that the label was correctly applied:

I updated the theme to use the endpoint http://192.168.103.1:8001/custom-labels/:

(local) 👻 > update guitheme id=69e6e38b-8a56-442c-9ff4-141138a37b2f customlabelspath="http://192.168.103.1:8001/custom-labels/"
{
  "guiThemes": {
    "created": "2026-06-12T21:38:03+0000",
    "css": ".layout.ant-layout .header {background: orange;}",
    "customlabelspath": "http://192.168.103.1:8001/custom-labels/",
    "id": "69e6e38b-8a56-442c-9ff4-141138a37b2f",
    "ispublic": true,
    "name": "test",
    "recursivedomains": false
  }
}

In this endpoint, there was an en.json file with the following content:

{
  "label.name": "Server name",
  "label.state": "Server state"
}

Navigating through the ACS GUI, I verified that the labels were also applied:

How did you try to break this feature and the system with this change?

hsato03 · 2026-06-12T22:04:25Z

@blueorangutan package

blueorangutan · 2026-06-12T22:06:05Z

@hsato03 a [SL] Jenkins job has been kicked to build packages. It will be bundled with no SystemVM templates. I'll keep you posted as I make progress.

codecov · 2026-06-12T22:13:05Z

Codecov Report

❌ Patch coverage is 0% with 46 lines in your changes missing coverage. Please review.
✅ Project coverage is 20.04%. Comparing base (0a5bf30) to head (4d5fc42).
⚠️ Report is 70 commits behind head on main.

Files with missing lines	Patch %	Lines
...rg/apache/cloudstack/gui/theme/GuiThemeJoinVO.java	0.00%	19 Missing ⚠️
...va/org/apache/cloudstack/gui/theme/GuiThemeVO.java	0.00%	8 Missing ⚠️
...ache/cloudstack/api/response/GuiThemeResponse.java	0.00%	6 Missing ⚠️
...ache/cloudstack/gui/theme/GuiThemeServiceImpl.java	0.00%	6 Missing ⚠️
.../api/command/user/gui/theme/CreateGuiThemeCmd.java	0.00%	3 Missing ⚠️
.../api/command/user/gui/theme/UpdateGuiThemeCmd.java	0.00%	3 Missing ⚠️
...src/main/java/com/cloud/api/ApiResponseHelper.java	0.00%	1 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##               main   #13415      +/-   ##
============================================
- Coverage     20.05%   20.04%   -0.01%     
+ Complexity    20656    20654       -2     
============================================
  Files          6427     6427              
  Lines        584905   584950      +45     
  Branches      71658    71659       +1     
============================================
- Hits         117278   117269       -9     
- Misses       454802   454858      +56     
+ Partials      12825    12823       -2

Flag	Coverage Δ
uitests	`3.72% <ø> (-0.01%)`	⬇️
unittests	`21.32% <0.00%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

blueorangutan · 2026-06-12T22:51:31Z

Packaging result [SF]: ✔️ el8 ✔️ el9 ✔️ el10 ✔️ debian ✔️ suse15. SL-JID 18246

JoaoJandre · 2026-06-17T16:44:26Z

@hsato03 could you fix the conflicts here?

github-actions · 2026-06-17T16:53:28Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

github-actions · 2026-07-02T18:46:03Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

hsato03 · 2026-09-25T21:33:23Z

@blueorangutan package

github-actions · 2026-09-28T17:14:42Z

This pull request has merge conflicts. Dear author, please fix the conflicts and sync your branch with the base branch.

Damans227 · 2026-10-15T13:52:16Z

  }

+  if (response?.customlabelspath) {
+    updateMessages(response.customlabelspath)


should we wait for the custom labels before the app mounts? the fetch isnt awaited so the first screen can still show the default labels

Damans227 · 2026-10-15T13:52:17Z

 }

+export function updateMessages (customPath) {
+  fetch(`${customPath}/${systemLang}.json`)


what happens when a user switches language? looks like the custom labels are only loaded for the language picked at startup

Add support for custom GUI labels to the GUI whitelabel runtime system

133c2c0

boring-cyborg Bot added component:api component:UI labels Jun 12, 2026

winterhazel added this to the 4.23.0 milestone Jun 15, 2026

winterhazel added status:needs-testing status:needs-review labels Jun 15, 2026

github-actions Bot added the status:has-conflicts label Jun 17, 2026

Resolve conflicts

273d1c3

github-actions Bot removed the status:has-conflicts label Jun 26, 2026

weizhouapache modified the milestones: 4.23.0, 4.24.0 Jun 29, 2026

github-actions Bot added the status:has-conflicts label Jul 2, 2026

DaanHoogland added this to CloudStack Testing Aug 10, 2026

github-project-automation Bot moved this to Backlog in CloudStack Testing Aug 10, 2026

DaanHoogland moved this from Backlog to conflict/waiting for author in CloudStack Testing Aug 31, 2026

Resolve conflicts

4d5fc42

github-actions Bot added status:has-conflicts and removed status:has-conflicts labels Sep 25, 2026

Damans227 reviewed Oct 15, 2026

View reviewed changes

Navigation Menu

Repository navigation

Add support for custom UI labels to the GUI whitelabel runtime system - #13415

Add support for custom UI labels to the GUI whitelabel runtime system#13415
hsato03 wants to merge 3 commits into
apache:mainfrom
scclouds:gui-theme-add-white-label-for-messages

hsato03 commented Jun 12, 2026

Uh oh!

hsato03 commented Jun 12, 2026

Uh oh!

blueorangutan commented Jun 12, 2026

Uh oh!

codecov Bot commented Jun 12, 2026 •

edited

Loading

Uh oh!

blueorangutan commented Jun 12, 2026

Uh oh!

JoaoJandre commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jul 2, 2026

Uh oh!

hsato03 commented Sep 25, 2026

Uh oh!

github-actions Bot commented Sep 28, 2026

Uh oh!

Damans227 Oct 15, 2026

Uh oh!

Damans227 Oct 15, 2026

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

hsato03 commented Jun 12, 2026

Description

Types of changes

Feature/Enhancement Scale or Bug Severity

Feature/Enhancement Scale

Bug Severity

Screenshots (if appropriate):

How Has This Been Tested?

How did you try to break this feature and the system with this change?

Uh oh!

hsato03 commented Jun 12, 2026

Uh oh!

blueorangutan commented Jun 12, 2026

Uh oh!

codecov Bot commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

blueorangutan commented Jun 12, 2026

Uh oh!

JoaoJandre commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jun 17, 2026

Uh oh!

github-actions Bot commented Jul 2, 2026

Uh oh!

hsato03 commented Sep 25, 2026

Uh oh!

github-actions Bot commented Sep 28, 2026

Uh oh!

Damans227 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

Damans227 Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov Bot commented Jun 12, 2026 •

edited

Loading