Table of Contents

String resources

String resources are localizable texts identified by a name and a value.
They can be used in UI templates as well as C# code when you need to localize a string value.
This typically concerns captions and messages that are displayed to the user.

Scope

This is the scope of the string resource. By the default, the scope is Shared. This means that the string resource can be used in frontend and backend code. You can specify the following scopes:

  • Shared: The string resource can be used in both frontend and backend code.
  • Backend: The string resource can only be used in backend code. No frontend code is generated for this string resource.
  • Frontend: The string resource can only be used in frontend code. No backend code is generated for this string resource. C# code is only generated for the abstraction.

By specifying the scope, you can control where the string resource can be used and optimize the generated code for your application.

Switching scopes

In Neos Studio, you can switch the scope of a string resource by using the Change scope action.

Shared to Backend

If you switch the scope from Shared to Backend, the string resource will only be available in backend code. When the application is generated, if the string resource is used in frontend code, you will get a generation error.

Shared to Frontend

If you switch the scope from Shared to Frontend, the string resource will only be available in frontend code. When the application is compiled, if the string resource is used in backend code, you will get a compilation error.

Creating a new string resource

String resources are grouped by modules. They can be created in different ways in Neos Studio.

Creating from the menu

  • In the menu, expand the module that will contain the resource
  • Expand Shared
  • Click on String resources
  • Click on Add

Then you can set a name and a module. This determines the name of the resource.
The name to use in C# code and templates can be copied.

Use the flag buttons to set the value for each language.
You can also click on the Translate button to open a modal which displays every managed languages at once. You can then set the value for one language and click on the Translate button to automatically translate what you typed to other languages using AI.
To configure the AI, see this article.

Creating from the code editor

When typing C# code or a UI template in Neos Studio, you can quickly access and edit string resources from the right click.

String resources list
You can access the list of the string resources of the cluster at any time using the String resources entry.

Creating a new string resource
If you have no selection, the New string resource entry opens a modal for creating a new string resource.
The module is automatically filled based on the module of the element you are editing.

If you have selected some text before right-clicking, you can select Create / edit string resource. This opens the same modal.
If your selection looks like a string resource name (Resources.[ModuleName].[ResourceName] or @Resources.[ModuleName].[ResourceName] or [ModuleName].[ResourceName]), the module and name are automatically set.
Otherwise, the module is set based on the module of the element you are editing and the default language value is set with the selected text.

When you set a name that already exists, a message invites you to load the existing string resource.
You can either accept, which overwrites your changes with the existing string resource values, or you can reject and enter a new name.

When you are done, you can click on the Insert into code or Insert into template button. This saves the string resource.
If you had a selection, it is replaced with the name of the string resource. Otherwise, the name of the string resource is inserted at the position of your cursor.
You can also manually save and close the modal.

Editing an existing string resource
You can edit an existing string resource by selecting its name and choosing Create / edit string resource in the right-click menu.
You can either select Resources.[ModuleName].[ResourceName] or @Resources.[ModuleName].[ResourceName] or [ModuleName].[ResourceName].

Using string resources

Getting a string resource in C# code

Using string resources in the code is done the same way for each of the following elements :

  • business assembly code (in Visual Studio)
  • validation rules
  • event rules
  • expressions

The syntax to use is:

  • UIResources.[ModuleName].[ResourceName] if the resource scope is Frontend.
  • AppResources.[ModuleName].[ResourceName] if the resource business assembly layer is Application.
  • Resources.[ModuleName].[ResourceName] if the resource business assembly layer is Domain.

UIResources.[ModuleName].[ResourceName] is a frontend-specific access path. If you want to use that syntax, the string resource must use the Frontend scope. Do not assume that a Shared string resource is available through UIResources.

string productName = "Apple";
int availableUnits = 2;

string message1 = Resources.Sales.InvalidCustomerSolvency;
string message2 = string.Format(Resources.Catalog.NumberAvailableUnitsProduct, productName, availableUnits);

The language of the string you get varies depending on the place you use this code and the context.

Server-side C#

This applies to server methods, business assembly code, entity view code, ...

If the C# code is executed in response to an HTTP request, you get the string in the language of the Accept-Language header.
If this header is not found or none of its languages is supported by the cluster, you get the string in the default language of the cluster.

Instead of just getting a string from you string resource, you can also get a LocalizableString object which contains all the translations of the string resource.
This requires localization settings to be injected in the constructor of your C# class thanks to dependency injection.

using GroupeIsa.Neos.Domain;

...

ILocalizationSettings _localizationSettings; // Injected

LocalizableString localizableString1 = AppResources.Sales.GetLocalizableString(
    _localizationSettings,
    nameof(AppResources.Sales.InvalidCustomerSolvency));
string englishMessage1 = localizableString1.DefaultTranslation;
string frenchMessage1 = localizableString1["fr"];

LocalizableString localizableString2 = LocalizableString.FromResource(
    _localizationSettings,
    AppResources.Sales.ResourceManager,
    nameof(AppResources.Sales.InvalidCustomerSolvency));
string englishMessage2 = localizableString2["en"];
string frenchMessage2 = localizableString2.GetTranslationOrDefault("fr");
string englishMessageBecauseGermanIsNotSupported = localizableString2.GetTranslationOrDefault("de");

Localizable strings can also be formatted :

using GroupeIsa.Neos.Domain;

...

ILocalizationSettings _localizationSettings; // Injected

string productName = "Apple";
int availableUnits = 2;

LocalizableString localizableString1 = AppResources.Catalog.GetFormattedLocalizableString(
    _localizationSettings,
    nameof(AppResources.Catalog.NumberAvailableUnitsProduct),
    productName,
    availableUnits);
string englishMessage = localizableString1.DefaultTranslation;
string frenchMessage = localizableString1["fr"];
string englishMessageBecauseGermanIsNotSupported = localizableString1.GetTranslationOrDefault("de");

LocalizableString localizableString2 = LocalizableString.FromFormattedResource(
    _localizationSettings,
    AppResources.Catalog.ResourceManager,
    nameof(AppResources.Catalog.NumberAvailableUnitsProduct),
    productName, availableUnits);
string englishMessage2 = localizableString2["en"];
string frenchMessage2 = localizableString2.GetTranslationOrDefault("fr");

Client-side C#

This applies to UI view code, UI shared methods, ...

You get the string in the preferred language of the web browser.
If none of these languages is supported by the cluster, you get the string in the default language of the cluster.

You cannot get a LocalizableString object from a resource because you cannot use dependency injection in UI C# code.

Displaying a string resource in UI templates

The syntax to use resources is : @Resources.[ModuleName].[ResourceName]

<heading level=1>@Resource.Sales.OrderTitle</heading>

This displays the resource in the preferred language of the web browser.
If none of the preferred languages of the browser are supported by the cluster, the string is displayed in the default language of the cluster.