[MikeAlhayek]

Summary

Some APIs need a LocalizedString or a LocalizedHtmlString, but there is no localizer where the value is created. Today the code repeats the same text for the name and the value:

entry.DisplayName = new LocalizedString(providerName, providerName);

This PR adds a static Create(string value, params object[] arguments) method to both types, as C# 14 extension members, so that the text is written only once:

entry.DisplayName = LocalizedString.Create(providerName);
var message = LocalizedHtmlString.Create("<strong>Hello</strong>");
var greeting = LocalizedString.Create("Hello {0}", userName);

The value is also used as the name. This works because Orchard Core uses the English text both as the default value and as the name of a localized string.

This is the first PR of a stack:

1. This PR: add LocalizedString.Create and LocalizedHtmlString.Create.
2. Use LocalizedString.Create for deployment step categories #19934: use LocalizedString.Create for the category of every deployment step.
3. Use LocalizedString for permission descriptions #19936: use LocalizedString for permission descriptions.

Changes

• LocalizedStringExtensions in the Microsoft.Extensions.Localization namespace, and LocalizedHtmlStringExtensions in the Microsoft.AspNetCore.Mvc.Localization namespace. Both are in OrchardCore.Abstractions/Localization/Extensions. Every Orchard Core project references OrchardCore.Abstractions, so the extensions can be used everywhere, including in OrchardCore.Infrastructure.Abstractions. They use the same namespaces as the types. Code that already uses the types can call LocalizedString.Create(...) with no new using directive.
• Create(value) is the same as new LocalizedString(value, value) and new LocalizedHtmlString(value, value). It does not translate the value, and ResourceNotFound is false.
• Like S["...", a, b] and H["...", a, b], Create accepts optional format arguments. The name stays the unformatted text. For a LocalizedString, the value is formatted with the arguments. For a LocalizedHtmlString, the arguments are HTML encoded when the string is rendered. With no arguments, the text is not formatted, so "Hello {0}" does not throw.
• Code that does not use C# 14 can call LocalizedStringExtensions.Create(...) or LocalizedHtmlStringExtensions.Create(...).
• Docs: a new "Creating a localized string without a localizer" section in reference/modules/Localize/README.md, and a 4.0.0 release notes entry.

Tests

• New LocalizedStringExtensionsTests and LocalizedHtmlStringExtensionsTests in OrchardCore.Tests.
• dotnet test --project test/OrchardCore.Tests -c Release --filter-class "*LocalizedStringExtensionsTests" --filter-class "*LocalizedHtmlStringExtensionsTests" --filter-class "*NullStringLocalizerTests": 33 passed.

Related

The PO extractor will pick up LocalizedString.Create("...") and LocalizedHtmlString.Create("...") when the argument is literal text: OrchardCoreContrib/OrchardCoreContrib.PoExtractor#130

🤖 Generated with Claude Code

[hishamco]

Please hold on .. we might need to discuss this with @sebastienros. If there's an option within the UI to change this, then DataLocalizer might fit here; otherwise will check the HTML localizer

[sebastienros]

Pending comment reviews

[hishamco]

This is weird, because the resource is not found, so the question is where the localization string should come from?

@sebastienros, how does this align with localization strings that come from PO files?!!

[hishamco]

@Skrypt, any thoughts?

[Skrypt]

If it is not found it will probably take the T["english string"] directly.

[sebastienros]

This can't be right, the values of the arguments can only be provided on render, and the same localization string can be rendered many times with different values.