How To Translate 20/20 DataShed

Step 1: Add a new <language> node to the languages.xml file by copy-n-pasting the original <language> node.

1. Access your web site with an FTP application such as CuteFTP, FTP Explorer, or Windows "My Network Places".
2. Download languages.xml from the templates folder of this application to your local computer.
3. Open languages.xml in a text editor such as Notepad. We recommend that you do not use a WYSIWYG editor like Frontpage or Dreamweaver for this purpose.
4. Locate the opening and closing tags of the <language> node. Select that node and everything (all of its "children") inside that node and copy (CTRL+C) the text. Example (Locate and copy the contents outlined in blue below):

   <?xml version="1.0" encoding="utf-8" ?>
   <languages>
         <language>
               <friendlyName>English (Canada)</friendlyName>
               <culture>en-ca</culture>
               <strings context="public">
                     <string>[fieldUsername]:</string>
                     ... ... (etc) ... ...
               </strings>
               <strings context="admin">
                     <string>Administration</string>
                     ... ... (etc) ... ...
               </strings>
         </language>
   </languages>

5. Paste the new content below the original node. As follows:

   <?xml version="1.0" encoding="utf-8" ?>
   <languages>
         <language>
               <friendlyName>English (Canada)</friendlyName>
               <culture>en-ca</culture>
               <strings context="public">
                     <string>[fieldUsername]:</string>
                     ... ... (etc) ... ...
               </strings>
               <strings context="admin">
                     <string>Administration</string>
                     ... ... (etc) ... ...
               </strings>
         </language>
         <language>
               <friendlyName>English (Canada)</friendlyName>
               <culture>en-ca</culture>
               <strings context="public">
                     <string>[fieldUsername]:</string>
                     ... ... (etc) ... ...
               </strings>
               <strings context="admin">
                     <string>Administration</string>
                     ... ... (etc) ... ...
               </strings>
         </language>
   </languages>

Step 2: Modify the new <language> node so that 20/20 DataShed recognizes it as a new language.

1. Now it is important that we alter the "friendlyName" and "culture" nodes so that 20/20 DataShed can identify this node (this new language) properly. Study the example below and make the necessary changes to your file:

   <?xml version="1.0" encoding="utf-8" ?>
   <languages>
         <language>
               <friendlyName>English (Canada)</friendlyName>
               <culture>en-ca</culture>
               <strings context="public">
                     <string>[fieldUsername]:</string>
                     ... ... (etc) ... ...
               </strings>
               <strings context="admin">
                     <string>Administration</string>
                     ... ... (etc) ... ...
               </strings>
         </language>
         <language>
               <friendlyName>French (Switzerland)</friendlyName>
               <culture>fr-ch</culture>
               <strings context="public">
                     <string>[fieldUsername]:</string>
                     ... ... (etc) ... ...
               </strings>
               <strings context="admin">
                     <string>Administration</string>
                     ... ... (etc) ... ...
               </strings>
         </language>
   </languages>

   Note that there is a complete cultural reference where you can find the appropriate "fiendly name" and "short name" for your language in 20/20 DataShed's _culture_info.xml file or online at 2020datashed.com.
2. Save the file.
3. From this point forward, we recommend that you upload the file to your web site and begin using it. You can alter one sentence at a time and see the changes in 20/20 DataShed as you go. As well, it is important to recognize errors as you make small changes (otherwise it is very difficult to track down an error.) Upload the file to your web site using the FTP application and overwrite the existing languages.xml file.
4. Refresh the application cache by visiting the login.asp page of 20/20 DataShed on your web site and add the ?objApplication=RemoveAll command to the querystring. Example: www.your_website.com/login.asp?objApplication=RemoveAll. This will force 20/20 DataShed to reload the language package (with your new contents).
5. At this point, if you have caused an error in the XML file, you will immediately see an error message on the web page. In this case we recommend that you restore the original languages.xml and return to step 1 and start again.
6. Login to a user account in 20/20 DataShed that has permission to access the "Options" control panel. You will notice a new option in the "thisAppDefaultLanguage" drop-down list.
   
   Select the new language option in this list and click "Update". From this point forward, 20/20 DataShed will use the text contained in this language node...as you proceed through step 3 you will notice the text on each page change as you translate.

Step 3: Translate the text in the new <language> node.

At this point you have already duplicated the original <language> node and have given it a new name. In our example we've used "French (Switzerland)" with the local identifier (<culture>) "fr-ch".

As well, you have uploaded the new languages.xml file to your web site and have instructed 20/20 DataShed to begin using the new <language> node.

The only task left is to actually translate each <string> node. To accomplish this follow the steps below for each string. (There are a few hundred separate strings...so this may be a very long process.)

To translate a single <string>, follow these steps:

1. Locate the <string> node to be translated. Example:

   <string>Sorry, your account has not been authorized yet by the administration. You will receive an email message when your account is authorized.</string>

2. Change the text between the <string></string> tags so that it now reads (in your own language):

   <string>Désolé, votre compte n'a pas été autorisé encore par l'administration. Vous recevrez un message d'email quand votre compte est autorisé.</string>

3. Save the file.
4. Upload the file to replace the current languages.xml file.
5. Refresh the server memory (application cache) by adding the objApplication=RemoveAll command to the querystring. For example: www.your_website.com/login.asp?objApplication=RemoveAll.
6. View the translated text to ensure that it appears correctly. Note that some text is seen only under special circumstances. For example, this particular example sentence is only presented on the login.asp page which a new user attempts to log into an user account that has not yet been authorized.

Additional Notes

We chose a very easy example above. But the reality is that each <string> in the languages.xml file may contain additional tokens or dynamic data. Consider the following examples:

<string>[fieldUsername]:</string>

This particular example does not need to be translated (although you might choose to translated it anyways). It is currently designed to draw the current field name of the "username" field.

On an English web site, that field is probably called "Username". On a French web site, that field is probably called "Nom d'utilisateur".

So in effect the [fieldUsername] token will be automatically replaced with the word "Nom d'utilisateur" on the French web site. Hence, this particular <string> does not need to be manually translated.

<string>Option: defaultSecurityRoles<![CDATA[<br /><br />]]>This option controls which security roles new [user_plural] should be automatically assigned to when they register in [thisAppTitle]. Note that these settings are effectively only if userIsApprovedByDefault is set to 'Yes'.<![CDATA[<br /><br />]]>Any combination of security roles can be selected.</string>

This example combines a lot of dynamic tools. First let's understand the output of this <string> on an English web site:

Option: defaultSecurityRoles
<br /><br />
This option controls which security roles new agents should be automatically assigned to when they register in Big Bob's Auto Sales. Note that these settings are effectively only if userIsApprovedByDefault is set to 'Yes'.
<br /><br />
Any combination of security roles can be selected.

1. Note first that the information contained in the <CDATA[[]]> tokens is transferred directly as HTML code to the page to create line breaks in the output.
2. Next, note that the [user_plural] token is replaced by the word "agents".
3. Next, note that the [thisAppTitle] token is replaced by the friendly name of the application: "Big Bob's Auto Sales".

On an French web site, the output might appear like this:

Option: defaultSecurityRoles
<br /><br />
Cette option commande à la laquelle on devrait automatiquement assigner des rôles de sécurité nouveaux agents quand ils s'enregistrent dedans Big Bob's Auto Sales. Notez que ces arrangements sont efficacement seulement si l'userIsApprovedByDefault est placé à 'oui'.
<br /><br />
N'importe quelle combinaison des rôles de sécurité peut être choisie.

Hmmm...This doesn't really work because the grammar is incorrect. So, in the French language <strings> it may be necessary to adjust the placement of the tokens or remove the tokens completely and use static words instead of dynamic information in the tokens. For more information about using tokens in the languages.xml file, see this Tokens Reference.

Each language, and in fact each unique web site, may require exceptional treatment. Our goal in creating the languages.xml file and the tokens was to provide customers with enough flexibility that they may create an effective translation for their needs. We apologize if this process seems mysterious or complex...but we are confident that our customers will find these tools invaluable once they are comfortable with the usage and purpose of each token.