How to: Localize Custom String Constants

• Mar 16, 2021
• 4 minutes to read

This topic demonstrates how to localize custom strings, using confirmation messages as an example. The Application Model has the Localization node, which allows for the localization of various constants. You can use this node to localize any custom strings used in your applications.

For instance, a feature that you implement in your application could use 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

Add Localization Items in the Model Editor

To make the text of the confirmation message above localizable, you can add a LocalizationItem child node to the Localization | Messages node, and specify its Value property in the required language. The following image demonstrates the necessary changes to be done in the Application Model.

In this instance, you can get the required message text from the new node, using the static CaptionHelper.GetLocalizedText method.

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 decide that you will have to localize multiple custom strings, you can add a special LocalizationGroup node to the Localization node, and specify your strings within it. Following our example, call this node Confirmations. The following image demonstrates these changes.

In this instance, use the following code.

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 create a complex hierarchy and access a required item by passing the path to the CaptionHelper.GetLocalizedText method. Do not include the Localization node itself to the path. For instance, to access the Localization | Messages | Confirmations | DataChangingConfirmations group, use the “Messages\Confirmations\DataChangingConfirmations” path.

Export Localization Items from Resource Files

Alternatively, you can add Localization Items from the 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

Here, “MySolution.Module.MyResource” is the resource name. Items from this resource will be added to the Localization | Messages | Confirmations Localization Group. Register this Resource Localizer within a module by adding its type to the ModuleBase.ResourcesExportedToModel collection.

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 within 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 will have an ability to add or remove a localizer in the Application Designer.

Note

Localizer types, which 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 the work of the Visual Studio design time environment, which 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 will see that items from the MyResource.resx resource are exported to the Application Model.

Now, you can use the CaptionHelper.GetLocalizedText method to access localizable values from your code.