Localizing And Customizing Texts

CONTENTS

Introduction
The IStaticLocalizationPlugin interface
The IDynamicLocalizationPlugin interface
Full example
List of Localization keys

Please see the Example A.402 - "Customize Piczard / Localize & customize texts"

1. Introduction

Piczard is provided with 2 built-in localizations:

en - English (default language)
it - Italian

You can add additional translations and/or customize texts by implementing one of the two Plugin interfaces that Piczrd provides:

IStaticLocalizationPlugin (If you want to use the same localized texts in every PictureTrimmer instance)
IDynamicLocalizationPlugin (if you need to customize texts so that each PictureTrimmer instance shows different texts)

For more information about Piczard Plugins, please see:

The property Culture of the PictureTrimmer control allows to select which translation to use.
Accepted values are:

A secific culture name (eg: "en-US")
A non specific culture name (eg: "en")
Empty string (use default culture System.Threading.Thread.CurrentThread.CurrentUICulture)

2. The IStaticLocalizationPlugin interface

The IStaticLocalizationPlugin interface consists of 2 methods:

GetCultures
This method must return an array of strings containing the list of culture names handled by the Plugin.
Example:

List of handled cultures Copy Code

public PluginOperationResult<string[]> GetCultures()
{
return base.GetHandledResult<string[]>(new string[] { "fr", "en-TT" });
}

List of handled cultures	Copy Code
public PluginOperationResult<string[]> GetCultures() { return base.GetHandledResult<string[]>(new string[] { "fr", "en-TT" }); }

GetDictionary
This method accept as parameter a name of a cutlure (one of those returned by the GetCultures method, e.g. "fr") and must return a generic Dictionary object having:

The localization key (e.g. "PPT_Popup_Button_Save") as dictionary key - Please see the List of localization keys
The localized text as dictionary value

Example:

Returning translated/customized texts	Copy Code
public PluginOperationResult<Dictionary<string, string>> GetDictionary(string culture) { if (culture == "fr") { // Manage the "fr" culture // Load an xml file containing the localized texts string filePath = HttpContext.Current.Server.MapPath("~/App_Data/CodeCarvings.Piczard.fr.resx.xml"); Dictionary<string, string> result = CodeCarvings.Piczard.Globalization.GlobalizationManager.LoadDictionaryFromXMLFile(filePath); return base.GetHandledResult<Dictionary<string, string>>(result); } if (culture == "en-TT") { // Manage the "en-TT" culture Dictionary<string, string> result = new Dictionary<string, string>(); // Customize only 2 texts (other texts are not customized) result["PT_MUI_Text_Details"] = "Details [en-TT]"; result["PT_MUI_Text_Original"] = "Source:"; return base.GetHandledResult<Dictionary<string, string>>(result); } // Culture not handled... return base.GetNotHandledResult<Dictionary<string, string>>(); }

Returning translated/customized texts

Copy Code

public PluginOperationResult<Dictionary<string, string>> GetDictionary(string culture)
{

   if (culture == "fr")
   {
       // Manage the "fr" culture
       // Load an xml file containing the localized texts
       string filePath = HttpContext.Current.Server.MapPath("~/App_Data/CodeCarvings.Piczard.fr.resx.xml");
       Dictionary<string, string> result = CodeCarvings.Piczard.Globalization.GlobalizationManager.LoadDictionaryFromXMLFile(filePath);
       return base.GetHandledResult<Dictionary<string, string>>(result);
   }
   if (culture == "en-TT")
   {
       // Manage the "en-TT" culture
       Dictionary<string, string> result = new Dictionary<string, string>();
       // Customize only 2 texts (other texts are not customized)
       result["PT_MUI_Text_Details"] = "Details [en-TT]";
       result["PT_MUI_Text_Original"] = "Source:";
       return base.GetHandledResult<Dictionary<string, string>>(result);
   }
   // Culture not handled...
   return base.GetNotHandledResult<Dictionary<string, string>>();
}

You can use the LoadDictionaryFromXMLFile method to load a dictionary directly from a resource XML file.

Within the Piczard installation directory (usually "C:\Program files\CodeCarvings\Piczard V1\"), subfolder "Resources\Globalization", you may find the xml resource files relative to the Piczard default languages:

CodeCarvings.Piczard.en.resx.xml
CodeCarvings.Piczard.it.resx.xml

Please note that It is not necessary that the dictionary contains all the localization keys.
For example, if you need to translate/customize only one text, you can return a dictionary containing only 1 element.

3. The IDynamicLocalizationPlugin interface

The IDynamicLocalizationPlugin interface consists of only 1 method: GetString

This method receives 3 parameters:

key - The key of the string to localize (e.g. "PPT_Popup_Button_Save". Please see the list of localization keys)
culture - The name of the culture in which the string has to be localized (e.g. "en" or "it-IT").
tag - An optional string that can be used to pass extra parameters during the dynamic localization process.
Please see: PictureTrimmer.Tag property.
For example, you can use this property to display different texts for different PictureTrimmer instances.

Example:

Returning translated/customized texts	Copy Code
public PluginOperationResult<string> GetString(string key, string culture, string tag) { string result = null; if (culture == "fr") { // Manage the "fr" culture switch (key) { case "PT_MUI_Text_Details": result = "Details"; if (tag == "ExA402_PopupPictureTrimmer") { result += " - Popup"; } break; case "PT_MUI_Text_Original": result = "Source:"; break; } } if (result != null) { // Return the custom text return base.GetHandledResult<string>(result); } else { // Use the default text return base.GetNotHandledResult<string>(); } }

Returning translated/customized texts

Copy Code

public PluginOperationResult<string> GetString(string key, string culture, string tag)
{
   string result = null;
   if (culture == "fr")
   {
       // Manage the "fr" culture
       switch (key)
       {
           case "PT_MUI_Text_Details":
               result = "Details";
               if (tag == "ExA402_PopupPictureTrimmer")
               {
                   result += " - Popup";
               }
               break;
           case "PT_MUI_Text_Original":
               result = "Source:";
               break;
       }
   }
   if (result != null)
   {
       // Return the custom text
       return base.GetHandledResult<string>(result);
   }
   else
   {
       // Use the default text
       return base.GetNotHandledResult<string>();
   }
}

4. Full example

Step 1 - Develop the localization Plugin

MyDynamicLocalizationPlugin.cs	Copy Code
namespace MyNamespace1 { public class MyDynamicLocalizationPlugin : Plugin, IDynamicLocalizationPlugin { public MyDynamicLocalizationPlugin(PluginConstructorArgs constructorArgs) : base(constructorArgs) { } protected override void Initialize(PluginInitializationArgs initializationArgs) { } public PluginOperationResult<string> GetString(string key, string culture, string tag) { if (culture == "it") { // Handle the "it" culture switch (key) { case "PT_MUI_Text_Details": return base.GetHandledResult<string>("DETTAGLI"); } } // Use the default text return base.GetNotHandledResult<string>(); } } }

MyDynamicLocalizationPlugin.cs

Copy Code

namespace MyNamespace1
{
   public class MyDynamicLocalizationPlugin
       : Plugin, IDynamicLocalizationPlugin
   {
       public MyDynamicLocalizationPlugin(PluginConstructorArgs constructorArgs)
           : base(constructorArgs)
       {
       }
       protected override void Initialize(PluginInitializationArgs initializationArgs)
       {
       }

       public PluginOperationResult<string> GetString(string key, string culture, string tag)
       {
           if (culture == "it")
           {
               // Handle the "it" culture
               switch (key)
               {
                   case "PT_MUI_Text_Details":
                       return base.GetHandledResult<string>("DETTAGLI");
               }
           }

           // Use the default text
           return base.GetNotHandledResult<string>();
       }
   }
}

Step 2 - Register the Plugin in the application configuration file

web.config	Copy Code
<?xml version="1.0"?> <configuration> <configSections> <sectionGroup name="codeCarvings.piczard"> <section name="coreSettings" type="CodeCarvings.Piczard.Configuration.CoreSettingsSectionHandler, CodeCarvings.Piczard" requirePermission="false"/> </sectionGroup> </configSections> <codeCarvings.piczard> <coreSettings> <plugins> <plugin type="MyNamespace1.MyDynamicLocalizationPlugin, MyAssemblyName" /> </plugins> </coreSettings> </codeCarvings.piczard> </configuration>

web.config

Copy Code

<?xml version="1.0"?>
<configuration>
<configSections>
   <sectionGroup name="codeCarvings.piczard">
     <section name="coreSettings" type="CodeCarvings.Piczard.Configuration.CoreSettingsSectionHandler, CodeCarvings.Piczard" requirePermission="false"/>
   </sectionGroup>
</configSections>
<codeCarvings.piczard>
   <coreSettings>
     <plugins>
       <plugin type="MyNamespace1.MyDynamicLocalizationPlugin, MyAssemblyName" />
     </plugins>
  </coreSettings>
</codeCarvings.piczard>
</configuration>

Step 3 - Use the Plugin

MyWebPage.aspx	Copy Code
<ccPiczard:InlinePictureTrimmer runat="server" ID="InlinePictureTrimmer1" Culture="it" />

5. List of Localization keys

The following are the defined localization keys and their default values:

Localization key	default value (en)
Web_Shared_Error_UnableToLoadResources	Piczard client-side library failed to load.
Web_Shared_Error_UpgradeFlashPlayer	You need to upgrade your Adobe Flash Player
PT_MUI_Text_Loading	Loading image...
PT_MUI_Text_NoImageLoaded	No image loaded
PT_MUI_Text_Details	Details
PT_MUI_Text_ZoomView	Zoom view
PT_MUI_Text_ResizeImage	Resize image
PT_MUI_Text_RotateFlipImage	Rotate / flip image
PT_MUI_Text_ImageAdjustments	Image adjustments
PT_MUI_Text_Original	Original:
PT_MUI_Text_Resized	Resized:
PT_MUI_Text_Cursor	Cursor:
PT_MUI_Text_WidthPrefix	W
PT_MUI_Text_HeightPrefix	H
PT_MUI_Text_Brightness	Brightness
PT_MUI_Text_Contrast	Contrast
PT_MUI_Text_Hue	Hue
PT_MUI_Text_Saturation	Saturation
PT_MUI_Tooltip_Original	Original image size (Width and Height) in {#uiUnit#}.
PT_MUI_Tooltip_Resized	Current image size (Width and Height) in {#uiUnit#}, using "Resize" factor: {#resizeFactor#}%.
PT_MUI_Tooltip_Cursor	Actual cursor location (from Top-Left corner) in {#uiUnit#}.
PT_MUI_Tooltip_SelectionLocation	Actual selection location (from Top-Left corner) in {#uiUnit#}.
PT_MUI_Tooltip_SelectionSize	Actual selection size (Width and Height) in {#uiUnit#}.
PT_MUI_Tooltip_Zoom	Current image zoom factor.
PT_MUI_Tooltip_Zoom_Slider	Dragging the cursor, the view will change (without changing any of the original parameters).
PT_MUI_Tooltip_Zoom_Reset	Reset the current image zoom factor.
PT_MUI_Tooltip_Resize	Current image resize factor.
PT_MUI_Tooltip_Resize_Slider	Dragging the cursor, the image will be resized.
PT_MUI_Tooltip_Resize_Reset	Reset the current image resize factor.
PT_MUI_Tooltip_Rotate	Rotate image: 0°, 90°, 180°, 270°.
PT_MUI_Tooltip_FlipH	Flip image horizontally.
PT_MUI_Tooltip_FlipV	Flip image vertically.
PT_MUI_Tooltip_Brightness	Current brightness.
PT_MUI_Tooltip_Brightness_Slider	Dragging the cursor, the brightness of the image will change.
PT_MUI_Tooltip_Contrast	Current contrast.
PT_MUI_Tooltip_Contrast_Slider	Dragging the cursor, the contrast of the image will change.
PT_MUI_Tooltip_Hue	Current hue.
PT_MUI_Tooltip_Hue_Slider	Dragging the cursor, the hue of the image will change.
PT_MUI_Tooltip_Saturation	Current saturation.
PT_MUI_Tooltip_Saturation_Slider	Dragging the cursor, the saturation of the image will change.
PT_MUI_Tooltip_ImageAdjustments_Reset	Reset every image adjustments parameter.
PT_MUI_Button_Zoom_Reset	Reset
PT_MUI_Button_Resize_Reset	Reset
PT_MUI_Button_ImageAdjustments_Reset	Reset
PPT_Popup_Button_Save	Ok
PPT_Popup_Button_Cancel	Cancel