Skip to content

Uibuilder/localization #7708

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
acoumb wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Uibuilder/localization #7708

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5baef69
Add additional localization documentation
acoumb Dec 10, 2025
96f13ec
Correct data views localization
acoumb Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 48 additions & 0 deletions 16/umbraco-ui-builder/collections/localization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,19 @@

Upon character identification in the fluent configuration, the localization context will attempt to lookup a matching localized string using two services available. If no matching record is found, it will default to the provided string value.

Supported areas:

* Collections - `Name` and `Description` properties.
* Data Views - only if the key is in a localization resource, not in the translation dictionary (e.g. [additional localization](#localizing-an-additional-area)).
Copy link
Contributor

@sofietoft sofietoft Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Data Views - only if the key is in a localization resource, not in the translation dictionary (e.g. [additional localization](#localizing-an-additional-area)).
* Data Views - only if the key is in a localization resource, not in the translation dictionary (learn more about [additional localization](#localizing-an-additional-area)).

* Collection filters - `Label` and `Description` properties.
* Cards
* Editor fields - `Label` and `Description` field properties.
* Fieldsets names
* Actions names
* Context Apps names
* Dashboards names
* Sections names

## Localization Services

The localization context uses two abstractions to provide localization options.
Expand Down Expand Up @@ -68,4 +81,39 @@

![section_name](../images/section_name.png)

### Localizing an additional area

In a scenario where a specific area is not covered by the implemented localization, you can update it directly in the fluent configuration by using the `LocalizationContext`.

Check warning on line 86 in 16/umbraco-ui-builder/collections/localization.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

Raw Output:
{"message": "[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.", "location": {"path": "16/umbraco-ui-builder/collections/localization.md", "range": {"start": {"line": 86, "column": 1}}}, "severity": "WARNING"}

For example, this custom data view:
Copy link
Contributor

@sofietoft sofietoft Dec 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For example, this custom data view:
See the following custom data view code snippet for an example:


```csharp
public class CommentStatusDataViewsBuilder : DataViewsBuilder<Comment>
{
private readonly LocalizationContext _localizationContext;
public CommentStatusDataViewsBuilder(LocalizationContext localizationContext)
{
_localizationContext = localizationContext;
}

public override IEnumerable<DataViewSummary> GetDataViews()
{
yield return new DataViewSummary
{
Name = _localizationContext.TryLocalize("#dataView_All", out string localizedText) ? localizedText : string.Empty,
Alias = "all",
Group = "Status"
};

foreach (var val in Enum.GetValues<CommentStatus>())
{
yield return new DataViewSummary
{
Name = val.ToString(),
Alias = val.ToString().ToLower(),
Group = "Status"
};
}
}
}
```
50 changes: 50 additions & 0 deletions 17/umbraco-ui-builder/collections/localization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,19 @@

Upon character identification in the fluent configuration, the localization context will attempt to lookup a matching localized string using two services available. If no matching record is found, it will default to the provided string value.

Supported areas:

* Collections - `Name` and `Description` properties.
* Data Views - only if the key is in a localization resource, not in the translation dictionary (e.g. [additional localization](#localizing-an-additional-area)).
* Collection filters - `Label` and `Description` properties.
* Cards
* Editor fields - `Label` and `Description` field properties.
* Fieldsets names
* Actions names
* Context Apps names
* Dashboards names
* Sections names

## Localization Services

The localization context uses two abstractions to provide localization options.
Expand Down Expand Up @@ -68,4 +81,41 @@

![section_name](../images/section_name.png)

### Localizing an additional area

In a scenario where a specific area is not covered by the implemented localization, you can update it directly in the fluent configuration by using the `LocalizationContext`.

Check warning on line 86 in 17/umbraco-ui-builder/collections/localization.md

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.

Raw Output:
{"message": "[UmbracoDocs.SentenceLength] Write shorter sentences (less than 25 words). For content inside note or warning blocks, add blank lines around the content.", "location": {"path": "17/umbraco-ui-builder/collections/localization.md", "range": {"start": {"line": 86, "column": 1}}}, "severity": "WARNING"}

For example, this custom data view:

```csharp
public class CommentStatusDataViewsBuilder : DataViewsBuilder<Comment>
{
private readonly LocalizationContext _localizationContext;
public CommentStatusDataViewsBuilder(LocalizationContext localizationContext)
{
_localizationContext = localizationContext;
}

public override IEnumerable<DataViewSummary> GetDataViews()
{
yield return new DataViewSummary
{
Name = _localizationContext.TryLocalize("#dataView_All", out string localizedText) ? localizedText : string.Empty,
Alias = "all",
Group = "Status"
};

foreach (var val in Enum.GetValues<CommentStatus>())
{
yield return new DataViewSummary
{
Name = val.ToString(),
Alias = val.ToString().ToLower(),
Group = "Status"
};
}
}
}
```


Loading