This tag enables you to define localized text (i.e. translated into different languages) for your forms. You use this tag to define the translations and the XMod function [[localize]] to display that text, based on the currently selected culture in DNN. There can be only one<localization> tag in your form, but you can have multiple [[localize]] functions. When you have multiple languages installed in DNN, users can choose which language they'd prefer to view the site in. When they select a language, your XMod forms can switch to that language as well. Please note that only static text can be localized. The data entered via XMod forms cannot be localized.
Here's an example of what the tag looks like:
<localization>
<culture name="en-US">
<data name="Name">Name</data>
<data name="Address">Address</data>
</culture>
<culture name="es-ES">
<data name="Name">Nombre</data>
<data name="Address">Dirección</data>
</culture>
<culture name="fr-FR">
<data name="Name">Nom</data>
<data name="Address">Adresse</data>
</culture>
<culture name="nl-NL">
<data name="Name">naam</data>
<data name="Address">adres</data>
</culture>
</localization>
As you can see in the example above, you create one <localization> ... </localization> tag pair that wraps everything else. Within this tag, you define one or more <culture> tags for each locale you wish to support. Each locale is identified by a name (also called a key). United States English is "en-US", English in Great Britain would be "en-GB", French spoken in France is "fr-FR", etc. If you're in doubt as to which name to use, login to your DNN site as Host (or SuperUser) and navigate to the "Languages" tab (under the Host menu). There you'll see a list of languages available for your DNN site (and have the opportunity to install others). For those installed languages, look in the "key" column to get the name to use.
Within the <culture> tag, you define one or more <data> tags. Define one for each piece of text you wish to localize. In the example above we have defined translations for "Name" and "Address". Each <data> tag is identified by a "name" attribute. In this case, the "name" is a key that your <xmod:label> tags will use to retrieve the appropriate text. Finally, the actual translated text is placed between the opening <data> and closing </data> tag. Here's an example of how you might use the above example data in your form:
<input ref="txtName">
<label>[[localize:Name|Your Name]]</label>
</input>
<input ref="txtAddress">
<label>[[localize:Address|Your Address</label>
</input>
Notice the <label> tags include a "lokey" attribute. This is short for localization key and they contain the value of the "name" attribute for the <data> tag for which we want the translated value. Notice that you don't have to specify a culture. XMod automatically grabs the current culture and ensures you get the text for that locale.
The <localization> tag has no attributes. Only one tag can be used per form. This tag can contain one or more <culture> tags. To incorporate translated text in your forms, you use it in conjunction with the [[localize]] function.
The <culture> tag encapsulates one or more <data> tags which, in turn, encapsulate the translated text.
|
name |
The key which uniquely identifies the language/culture for which the included <data> tags are targeted. Some examples are:
|
The <data> tag has the attributes listed below. It also encloses the actual translated text.
|
name |
The key which identifies the this translated text within a <culture> tag. This key should be unique for all <data> tags within the <culture> tag. The can (and should) be duplicated in other <culture> tags. The name attribute is used by [[localize]] functions to locate the correct translated text. |
In the example below, two labels are localized. Notice they contain English as the default text. This assumes the site has a default language of English so there is no reason to supply a <culture> tag for it. Instead, the site will display the default text. If the user switches to Spanish, French, or Dutch, then the appropriate translation for that language will be displayed.
<form>
<controls>
<input ref="Name" width="250px" class="NormalTextBox">
<label>[[localize:Name|Your Name]]</label>
</input>
<input ref="Address" width="250px" class="NormalTextBox"> </controls>
<label>[[localize:Address|Your Address]]</label>
</input>
</controls>
<localization>
<culture name="es-ES">
<data name="Name">Su Nombre</data>
<data name="Address">Su Dirección</data>
</culture>
<culture name="fr-FR">
<data name="Name">Votre Nom</data>
<data name="Address">Votre Adresse</data>
</culture>
<culture name="nl-NL">
<data name="Name">uw naam</data>
<data name="Address">uw adres</data>
</culture>
</localization>
</form>
The example below is a custom HTML version of the one above. So that it doesn't get in the way, we've grayed-out the HTML tags in order to focus on the localization-related tags. The labels are in red. Since you are in charge of the layout and design of the form, XMod cannot automatically use your <label> as the caption for the control. However, it is still required since XMod uses the <label> (in red, below) for display to the user elsewhere in the application. By using the[[localize]] function to localize the <label>, the localized text will display elsewhere in XMod (like in the drop-down list control used to select a field to sort on).
So, in this case, to get a localized label to display text, we need to add a second [[localize]] function (in blue) where we want the text displayed. As with the form above, each <label> contains English as the default text. This assumes the site has a default language of English so there is no reason to supply a <culture> tag in the <localization> tag for it. Instead, the site will display the default text. If the user switches to Spanish, French, or Dutch, then the appropriate translation for that language will be displayed.
We've also added a neat use of the [[localize]] function. In the beginning of the form (just after the <controls> tag), we're using the function to dynamically change the flag image that represents the current language selected. It defaults to the US flag (presumably en-US is the default language of the site in this example) and will change to the flags for Span, France, and the Netherlands if those languages are selected by the user.
Finally, you may notice this form doesn't use <literal> tags. Beginning about XMod 4.3, <literal> tags are no longer required for custom HTML forms as long as the form is well-formed XHTML. There may be some cases where you still need to use the <literal> tags, though - usually when including Javascript.
<form format="custom">
<controls>
<img src="/images/[[localize:LanguageImage|flag_us.gif]]" /><br />
<span style="padding-right: 10px;">[[localize:Name|Your Name]]</span>
<input ref="Name" width="250px" class="NormalTextBox">
<label>[[localize:Name|Your Name]]</label>
</input><br />
<span style="padding-right: 10px;">[[localize:Your Address]]</span>
<input ref="Address" width="250px" class="NormalTextBox">
<label>[[localize:Address|Your Address]]</label>
</input><br />
</controls>
<localization>
<culture name="es-ES">
<data name="LanguageImage">flag_spain.gif</data>
<data name="Name">Su Nombre</data>
<data name="Address">Su Dirección</data>
</culture>
<culture name="fr-FR">
<data name="LanguageImage">flag_france.gif</data>
<data name="Name">Votre Nom</data>
<data name="Address">Votre Adresse</data>
</culture>
<culture name="nl-NL">
<data name="LanguageImage">flag_netherlands.gif</data>
<data name="Name">uw naam</data>
<data name="Address">uw adres</data>
</culture>
</localization>
</form>