How to: Localize Custom String Constants

• Oct 24, 2022
• 4 minutes to read

This topic demonstrates how to localize custom strings. This example uses confirmation messages. The Application Model has the Localization node that allows localization of various constants. You can use this node to localize custom strings used in your applications.

For instance, a feature that you implement in your application uses the following code:

C#

using System.Windows.Forms;
// ...
if (MessageBox.Show("Do you wish to cancel your changes?", "", MessageBoxButtons.YesNo) 
   == DialogResult.Yes) {
   // ...
}

VB.NET

Imports System.Windows.Forms
' ...
If MessageBox.Show("Do you wish to cancel your changes?", "", MessageBoxButtons.YesNo) = _
DialogResult.Yes Then
   ' ...
End If

To localize custom strings from the WebApi context, refer to the following article: Access Caption Helper in Custom Endpoint Methods.

Add Localization Items in the Model Editor

To localize the text of the confirmation message above, add the LocalizationItem child node to the Localization | Messages node, and specify its Value property in the required language:

You can use the static CaptionHelper.GetLocalizedText method to get the required message text from the new node.

C#

using System.Windows.Forms;
using DevExpress.ExpressApp.Utils;
// ...
if (MessageBox.Show(CaptionHelper.GetLocalizedText("Messages", "DoYouWishToCancelChanges"), 
    "", MessageBoxButtons.YesNo) == DialogResult.Yes) {
    // ...
}

VB.NET

Imports System.Windows.Forms
Imports DevExpress.ExpressApp.Utils
' ...
If MessageBox.Show(CaptionHelper.GetLocalizedText("Messages", "DoYouWishToCancelChanges"), _
    "", MessageBoxButtons.YesNo) = DialogResult.Yes Then
    ' ...
End If

If you need to localize multiple custom strings, add the LocalizationGroup node to the Localization node and specify your strings there. In this example, this node is called Confirmations:

C#

using System.Windows.Forms;
using DevExpress.ExpressApp.Utils;
// ...
if (MessageBox.Show(CaptionHelper.GetLocalizedText(
    @"Messages\Confirmations", "DoYouWishToCancelChanges"), 
        "", MessageBoxButtons.YesNo) == DialogResult.Yes) {
    // ...
}

VB.NET

Imports System.Windows.Forms
Imports DevExpress.ExpressApp.Utils
' ...
If MessageBox.Show(CaptionHelper.GetLocalizedText( _
"Messages\Confirmations", "DoYouWishToCancelChanges"), _
"", MessageBoxButtons.YesNo) = DialogResult.Yes Then
    ' ...
End If

The LocalizationGroup node can have a multilevel structure. You can use the CaptionHelper.GetLocalizedText method to create a complex hierarchy. This method accepts a path as an input parameter. For instance, to access the Localization | Messages | Confirmations | DataChangingConfirmations group, use the “Messages\Confirmations\DataChangingConfirmations” path. Do not include the Localization node itself in the path.

Export Localization Items from Resource Files

You can add Localization Items from a resource file. Assume you have the following MyResource.resx resource file in your XAF solution:

To export values from this file to the Application Model, implement a Resource Localizer (XafResourceLocalizer descendant):

C#

using DevExpress.ExpressApp.Localization;
// ...
public class MyXafResourceLocalizer : XafResourceLocalizer {
    protected override IXafResourceManagerParameters GetXafResourceManagerParameters() {
        string[] localizationGroupPath = new string[] { "Messages", "Confirmations" };
        return new XafResourceManagerParameters(localizationGroupPath, 
            "MySolution.Module.MyResource", "", GetType().Assembly);
    }
}

VB.NET

Imports DevExpress.ExpressApp.Localization
' ...
Public Class MyXafResourceLocalizer
    Inherits XafResourceLocalizer
    Protected Overrides Function GetXafResourceManagerParameters() As IXafResourceManagerParameters
        Dim localizationGroupPath() As String = { "Messages", "Confirmations" }
        Return New XafResourceManagerParameters(localizationGroupPath, _
        "MySolution.Module.MyResource", "", Me.GetType().Assembly)
    End Function
End Class

In this snippet, “MySolution.Module.MyResource” is the resource name. Items from this resource are added to the Localization | Messages | Confirmations Localization Group. Add the Resource Localizer type to the ModuleBase.ResourcesExportedToModel collection to register the Resource Localizer in a module.

C#

public sealed partial class MySolutionModule : ModuleBase {
    public MySolutionModule() {
        // ...
        ResourcesExportedToModel.Add(typeof(MyXafResourceLocalizer));
    }
    // ...
}

VB.NET

Public NotInheritable Partial Class MySolutionModule
    Inherits ModuleBase
    Public Sub New()
        ' ...
        ResourcesExportedToModel.Add(GetType(MyXafResourceLocalizer))
    End Sub
    ' ...
End Class

Alternatively, you can register a resource localizer in the overridden ModuleBase.GetXafResourceLocalizerTypes method.

C#

public sealed partial class ResourceLocalizerModule : ModuleBase {
    // ...
    public override ICollection<Type> GetXafResourceLocalizerTypes() {
        ICollection<Type> localizers = base.GetXafResourceLocalizerTypes();
        localizers.Add(typeof(MyXafResourceLocalizer));
        return localizers;
    }
}

VB.NET

Public NotInheritable Partial Class ResourceLocalizerModule
    Inherits ModuleBase
    ' ...
    Public Overrides Function GetXafResourceLocalizerTypes() As ICollection(Of Type)
        Dim localizers As ICollection(Of Type) = MyBase.GetXafResourceLocalizerTypes()
        localizers.Add(GetType(MyXafResourceLocalizer))
        Return localizers
    End Function
End Class

In this instance, you can add or remove a localizer in the Application Designer.

Note

Localizer types that are defined in the current module are not displayed in the Resources exported to model dialog of the Module Designer. This behavior is by design and specific to how the Visual Studio design-time environment works. It cannot get the list of localizer types of the module itself because this information is not serializable.

Rebuild the solution and invoke the Model Editor. You can see that items from the MyResource.resx resource are exported to the Application Model.

You can now use the CaptionHelper.GetLocalizedText method to access localizable values from code.