Custom handling of diacritics

The system removes diacritics from text during many parsing operations. For example, diacritics are removed when indexing text for the smart search or when setting page aliases or URL slugs for pages. When the event is triggered, characters with diacritics are replaced by the appropriate base character, for example ü is converted to u.

If you need to change the default behavior of removing diacritics, you can register and implement a handler for the OnBeforeRemoveDiacritics event.

The event is a member of the TextHelper class, which can be found under the CMS.Helpers namespace.

  • The handler for this event has the source text included as a string parameter passed by reference, so any changes that you make in the code are reflected in the result.
  • The handler has a boolean return value that indicates whether the default functionality should also be performed after the handler is executed. For this reason, it is highly recommended to set the return value to true for all but the most extensive customizations.


Only return a false value if you are sure that your custom handler can take full responsibility for all diacritics removal requirements. Disabling the default system functionality may prevent parts of your website from working correctly.


The following example demonstrates how to define a handler for the diacritic removal event:

  1. Open your Xperience solution in Visual Studio.

  2. Create a custom module class.

    • Add the class into a custom Class Library project within the solution.
  3. Override the module’s OnInit method and assign the handler to the required event:

     using System;
     using CMS;
     using CMS.DataEngine;
     using CMS.Helpers;
     // Registers the custom module into the system
     [assembly: RegisterModule(typeof(CustomDiacriticsModule))]
     public class CustomDiacriticsModule : Module
         // Module class constructor, the system registers the module under the name "CustomDiacriticsHandling"
         public CustomDiacriticsModule()
             : base("CustomDiacriticsHandling")
         // Contains initialization code that is executed when the application starts
         protected override void OnInit()
             // Assigns a handler to the OnBeforeRemoveDiacritics event
             TextHelper.OnBeforeRemoveDiacritics += Custom_OnBeforeRemoveDiacritics;
  4. Add the Custom_OnBeforeRemoveDiacritics handler:

     static bool Custom_OnBeforeRemoveDiacritics(ref string text, EventArgs e)
         // Replaces German special characters
         text = text.Replace( "ä", "ae" );
         text = text.Replace( "ö", "oe" );
         text = text.Replace( "ü", "ue" );
         text = text.Replace( "Ä", "Ae" );
         text = text.Replace( "Ö", "Oe" );
         text = text.Replace( "Ü", "Ue" );
         text = text.Replace( "ß", "ss" );
         // Returns true to indicate that the default diacritics removal should also be performed
         return true;                

    This ensures that the system uses custom replacements for German special characters rather than simply stripping the diacritics and leaving the base character.

  5. Save the file and Rebuild the solution.

The system applies the changes when removing diacritics from text.

Note: The customization does not automatically change the page aliases of existing pages until the current value is changed or saved.