Localization of projects on .NET with a function interpreter

Prologue

1. The complexity of implementing an existing project.
2. Lack of formatting tools for localized messages (with the exception of the standard string.Format).
3. Inability to embed culturally dependent functions. For example, a typical task — substitution of the desired form of a word depending on the value of a number — cannot be resolved by dictionaries alone.

Library Composition

• Genesis.Localization is the main localization library.
• Ru - implementation of Russian localization (example).
• En - implementation of English localization (example).
• LocalizationViewer - a program to demonstrate the capabilities of the library with the ability to edit localizations.
  
  
  
  

Basic principles

Localization manager

// инициализация менеджера локализаций
LocalizationManager = new LocalizationManager();
LocalizationManager.BasePath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Localization");
LocalizationManager.Initialize();
try
{
    LocalizationManager.DetectAllLocalizations();
}
catch (LocalizationException ex)
{
    MessageBox.Show(ex.Message, "Ошибка локализации", MessageBoxButtons.OK, MessageBoxIcon.Error);
    return;
}

manager.Localizations

LocalizationPackage package = manager.Load("ru");

manager.Unload("ru");

Localization package

• localization.info - xml file with a brief description of the package, these files are initially downloaded by the localization manager.
  
  An example for Russian localization:
  
  

  Русскийru

  
  As you can see, there are only two fields, maybe later new fields will be added to identify a particular package.
• flag.png - an image symbolizing localization. In my examples, these are state flags with a size of 16x16 pixels.
• strings.xml - xml file containing localized strings. When overriding the logic of a package, you can create your own source of strings, for example, a binary or a database.
• package.dll - the executable module of the package is a small library in which a class inherited from LocalizationPackage must be present .
  
  Example of executable code for Russian localization:
  
  

  using System;
  using Genesis.Localization;
  namespace Ru
  {
      public class Package : LocalizationPackage
      {
          protected override object Plural(int count, params object[] forms)
          {
              int m10 = count % 10;
              int m100 = count % 100;
              if (m10 == 1 && m100 != 11)
              {
                  return forms[0];
              }
              else if (m10 >= 2 && m10 <= 4 && (m100 < 10 || m100 >= 20))
              {
                  return forms[1];
              }
              else
              {
                  return forms[2];
              }
          }
      }
  }
  

  
  An explanation will be given below of what the Plural method is.
  

Using localization packages

1. Getting a specific string by its key (classic method). The key can be a string or a number of type Int32.
   
   Usage example:
   

   LocalizationPackage package = manager.Load(culture);
   string strByName = package["name"];
   string strByID = package[150];
   

   
   
2. Getting a formatted string with passing arguments. This is the method for which the library was created.
   
   Usage example:
   

   LocalizationPackage package = manager.Load(culture);
   string formattedString = package["name", arg1, args2, ...];
   

   
   Any objects can be used as arguments. More details about this method will be described below.
   
   
3. Getting the path to a localized resource. To do this, use the GetResourceFilePath (string filename) method to get the path to an arbitrary file in the localization directory or the GetImage (string filename) method to load the image from there.

String interpreter

1. The inclusion of an argument in a string.
   
   Format Instructions:

   %index%
   

   
   Result: embedding the argument number index in the string
   
   Example of use:
   

   package.GetFormattedString("%1% = %0%%%", 80, "КПД");
   

   
   Result:
   

   КПД = 80%
   

   
   Please note that the % character , being a service character , must be escaped by another character that is the same as in this example.
   
   
2. Enabling features
   
   Format instructions:
   

   %Func(arg1, arg2, ..., argN)%
   

   
   
   The arguments can be numbers , double-quoted strings (the quotes themselves are escaped, like%, by double repetition), string arguments by their number (% index), or calls to other functions .
   
   Usage example:
   

   package.GetFormattedString("Игрок %1% наносит по вам %Upper(Random(\"сильный\", \"сокрушительный\", \"мощный\"))% удар, отнимая %0% %Plural(%0, \"единицу\", \"единицы\", \"единиц\")% здоровья.", 55, "MegaDeath2000");
   

   
   Result:
   

   Игрок MegaDeath2000 наносит по вам СОКРУШИТЕЛЬНЫЙ удар, отнимая 55 единиц здоровья.
   

   
   

Built-in Features and Integration

• Plural (int, var1, var2, ..., varN) - embedding the word form depending on the number, this method is unique for each culture and must be redefined. In particular, in the Russian language there are three forms of numbers (for example: “1 unit”, “2 units”, “8 units”).
• Random (var1, var2, ..., varN) - selection of a random value among the given ones.
• Upper (string) - cast to uppercase.
• Lower (string) - cast to lower case.
• UpperF (string) - casting to the upper case only the first letter ("word" => "Word").
• LowerF (string) - cast to the lower case only the first letter.

1. In the redefined class of the package, you can declare new functions and mark them with the [Function] attribute, then they will be automatically included in the interpreter for a specific localization. Built-in functions are defined in this way, for example, the Plural and Random functions look like this:
   
   

   [Function("P")]
   protected abstract object Plural(int count, params object[] forms);
   [Function]
   protected virtual object Random(params object[] variants)
   {
       if (variants.Length == 0)
       {
           return null;
       }
       else
       {
           return variants[_rnd.Next(variants.Length)];
       }
   }
   

   
   Please note that it is permissible for a function to specify a list of its aliases (for short record), for example, Plural can be called both through the main name ( Plural ) and through an alias ( P ), while the case in the names of the functions does not matter.
   
   
2. Integration of own functions, for this, the InjectFormatterFunction method is used , an example of use:
   
   

   var package = LocalizationManager.Load("ru");
   package.InjectFormatterFunction(new Func((a, b) => Math.Min(a, b)), "Min");
   package.InjectFormatterFunction(new Func((a, b) => Math.Max(a, b)), "Max");
   package.GetFormattedString("%min(%0, max(%1, %2))%", 10, 8, 5);
   

   
   Result:
   

   8
   

   
   A method (MethodInfo) or a delegate can be passed as an argument to an InjectFormatterFunction (delegates are passed in the example above).

Additional features

Debug mode

var package = LocalizationManager.Load("ru");
package["New Key"] = "Новое значение";
package.Save();

Mappings

[LocalizableClass("Text", "CAPTION")]
public partial class frmMain : Form
{
        ...
        [LocalizableClass]
        private System.Windows.Forms.ToolStripButton cmdExit;
        [LocalizableClass]
        private System.Windows.Forms.ToolStripButton cmdSave;
        [LocalizableClass]
        private System.Windows.Forms.ToolStripLabel lblSearch;
        ...
        /// 

        /// применяем локализацию
        /// 
        private void Localize()
        {
            LocalizationMapper mapper = new LocalizationMapper();
            mapper.Current = manager["ru"];
            mapper.Localize(this);
        }
        ...
}

LocalizationViewer.frmMain.cmdExit_Text