Localizing Strings

Have strings on forms in the language of your website

When you localize your website (say, from English to Danish), by default the input forms rendered by the Forms Renderer will only display their labels and validation messages in the main language (say, English).

To have the form labels and validation messages in the language of the localized website, you should:

1. Create a .NET resource file for each language and localize corresponding strings in such a file.
2. Use such strings in the field properties of the data type used by the Forms Renderer.

Note: The technical validation messages that appear when validation fails on the user's input in the field cannot be localized. However, you can have them automatically replaced with your user-friendly messages by providing Help texts for the data type fields used in your forms. These user-friendly messages can be localized.

Upgrading to the latest Composite.Forms.Renderer version

Before you start localizing forms, you should make sure that you have the latest version of Composite.Forms.Renderer installed. When upgrading, back up the files as described below:

1. If you have made any changes in files (for example, in CSS files) in the folder /Frontend/Composite/Forms, back up those files.
2. Uninstall the outdated Forms Renderer package (System > Packages > Installed packages > Composite.Forms > Composite.Forms.Renderer, click Package info and then Uninstall).
3. Install the latest version (System > Packages >vailable packages > Composite.Forms > Composite.Forms.Renderer, click Install and follow the steps in the wizard)
4. If you have backed up any files in Step 1, copy them back to their original location.

Creating the .NET resource file and localizing the strings

1. Open or create the /App_GlobalResources folder in the root of your website.
2. In this folder, create a .NET resource file (.resx) and name it something appropriate: for example, "MainContactForm.resx".
3. Copy the following XML into this file:
   

   <root> 
     <resheader name="resmimetype"> 
       <value>text/microsoft-resx</value> 
     </resheader> 
     <resheader name="version"> 
       <value>2.0</value> 
     </resheader> 
     <resheader name="reader"> 
       <value>System.Resources.ResXResourceReader, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value> 
     </resheader> 
     <resheader name="writer"> 
       <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=2.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value> 
     </resheader> 
     <!-- your strings goes here --> 
     <data name="Hello" xml:space="preserve">
       <value>Hello</value>
        <comment>Sample comment here - not displayed on the site. This is optional.</comment>
     </data> 
     <data name="HelloScandinavia" xml:space="preserve">
        <value>Hello Scandinavia</value>
     </data> 
     <data name="HelloWorld" xml:space="preserve">
        <value>Hello world</value>
     </data> 
   </root>

   
   This is the resource file for your main language.
4. Edit the file and add as many <data> elements as you need for each string you want to localize. You can edit it as an XML file or open it in Visual Studio which gives you a nice 'resource editor'.
   As you can see in the above XML, each string is represented by a <data> element, the name attribute of which specifies the name of the string you will refer to when localizing forms. As its name suggests, the <value> element specifies the value of this string, i.e. the string itself, which the user will see on a form.
5. For each language in addition to your main language, copy the file using the file naming pattern "[resource name].[culture name].resx": for example, "MainContactForm.da-DK.resx".
6. Localize the string values in those files.

Using resource strings in datatype field properties

Your resource files for the main and other languages are ready. Now you need to refer to the resource strings in the Label and Help datatype field properties in a correct way:

1. Edit the datatype used by the Forms Renderer for the form you want to localize.
2. Open the Fields tab and select a field under the Datatype fields.
3. At this point, if you have created a resource file named "MainContactForm" and a string named "NameLabel", you can specify "${Resource, Resources.MainContactForm.NameLabel}" as the label text for a field (the Label property), and the form field label will be translated.
   
   Likewise, you should specify strings for the help text of a field (in the Help property).
   
   In general, follow this pattern when referring to the resource strings from the data type field labels and help texts:

${Resource, Resources.[resource file name].[string name]}
   
   The name of the resource file must be written without the culture name (e.g. "en-us") and extension (".resx"). The string name must be attached to the resource file name and separated from the resource file name with a period (".").
4. Repeat Step 3 for the Label and Help properties of each datatype field.

Note: Changes to the /App_GlobalResources folder make ASP.NET (and hence C1) restart, which can make the application feel unresponsive right after updates.

Now the labels and help texts (that serve as user-friendly validation messages) are localized with the help of the corresponding resource files.

Troubleshooting

If you are experiencing an ASP.NET error screen saying that your resource can not be located etc, make sure that you have:

1. upgraded to the latest version of the Composite.Forms.Renderer package;
2. correctly named the file for the main language (without the culture name) and other languages (with the culture name);
3. correctly referred to the resource file and the string name in the datatype field properties (Label and Help).