Customizing Language Files

OVERVIEW

Localization of any website is not a small task.  We all know that.  The goal of this article is to help you find the localization files to make it easier for you to translate all of the necessary content that relates to Hotcakes Commerce.

REQUIREMENTS

The following pre-requisites will be necessary to accomplish the goals of this article:

• Basic understanding of how to administrate the CMS
• Review the Introduction to Localization article
• Basic understanding of localization
• Familiarity with localization (resx) files
• Ability to access the website file system and login as an Administrator/Superuser in the CMS

GETTING STARTED

This article will assume that you are using the CMS’ language editor feature when possible, but we will also point you to the right folder if you are choosing to edit these files using a more user-friendly editor, such as Visual Studio.

LOCATION OF LANGUAGE FILES

There are two locations where you will find language files for Hotcakes Commerce.  The first location is the traditional place where all modules keep language files.  This would be in the App_LocalResources sub-folder of Hotcakes.  The other language files are directly related to the viewsets that you have available out of the box and the same would apply to your custom viewsets.  Since the language files contain translations for the views themselves, the language files will be in the App_LocalResources folder for the respective views, in addition to a global resources file.  All of this will be discussed in more detail below.

Managing Language Files

You can choose to manage the language files in your site using the steps outlined in the next section below.  This works great, but if you're manage the language files locally on your computer, or if you have direct access to the server where your website is hosted, you might want to choose to use one of the 3rd party programs listed below instead.  Each program has its strengths and weaknesses and the right for you to use depends on how many change you want to make.

• Resx Crunch - This is an open source program that allows you to select language files one at a time, or point it at an entire directory and manage all of its language files all at the same time.
• DotNetNuke Translator - This is also an open source desktop program that allows you to do the same thing, but it requires that you only edit one language file at a time.

Settings Language File Locations

If you haven’t already, you should login as an administrator/superuser.  This article will perform the steps as a superuser.  Go ahead and navigate to the Languages feature in the CMS and choose to edit the Site language files.  It’s okay to edit the other ones if you want to define the scope of your updates more globally.

You will find the language files for the Settings view of each Hotcakes module in the following path.

~/DesktopModules/Hotcakes/[MODULENAME]/App_LocalResources/

MODULENAME is the name of the module you want to edit localization for.  For example, the “Checkout” module language file path would look like this.

~/DesktopModules/Hotcakes/Checkout/App_LocalResources/

Not all modules have or require a language file for it.  For example, the Address Book module does not contain an App_LocalResources folder.

Here is what that looks like in the Language editor, assuming you just chose the Cart module.

In order to edit these files, simply find the name of the translation you want to edit and make the necessary changes.  When you're done, scroll to the bottom and click the update button to save your changes

Viewset Language File Locations

The viewsets will have their localization files in relatively the same place as the view itself, following the same pattern as the rest of the CMS.  Unfortunately, the CMS does not look in the location where these files are located.  Therefore, the rest of this article will use Windows Explorer to show the location of the files.

Open the website folder for the site where Hotcakes is installed.  Navigate to the following path.

~/Portals/_default/HotcakesViews/[VIEWSETNAME]/Views/[VIEWNAME]/App_LocalResources/

VIEWSETNAME is the name of your custom viewset, and VIEWNAME is the name of the view you are translating.  If you are editing your own viewset named “MyViewset” and wanting to change the contents of the language for the AffiliateDashboard view, then the path you would be using would look like this.

~/Portals/_default/HotcakesViews/MyViewset/Views/AffiliateDashboard/App_LocalResources/

It is highly discouraged to not edit the _default viewset.  This is the viewset that comes out of the box with Hotcakes.  Any changes you make to the _default viewset will be overwritten upon every upgrade.  Please see the documentation for creating a custom viewset for more information on this topic.

There is another “global” language file for views as well.  This file contains shared language translations that are used across multiple views.  This file is located at the following path and is named GlobalResources.resx by default.

~/Portals/_default/HotcakesViews/[VIEWSETNAME]/Views/App_LocalResources/

If you are creating a new set of translations for a new language altogether, you would need to follow the same patterns and naming conventions that are in place in the file system and the CMS itself.

Always create and place files in the same folder locations as the existing languages.

Include the locale code for the new files in the file name.  The following two file names use the Global Resources file as an example, but it would apply to any language file.

English:  GlobalResources.resx

French:  GlobalResources.fr-FR.resx

Editing a Language File

When editing a language file, you should never change the Name field for existing translations.  Only modify the Value column by changing the text to be something different for your store, or by providing the translated text if you are creating the localized content for a new language.  Note the file name difference in the following example that illustrates the different Name/Value pairs for the same file in English and Spanish.

It is okay to add your own keys as well if you plan to include your own static content that requires translation.  Just be sure to include a prefix to ensure that your changes are easily distinguished should you ever need to refer back to your changes to determine what was custom and what was out of the box.

Adding the new key to your view is quite simple. An example is shown below.

<p>@Localization.GetString("MyCompany.NewLabel.Text")</p>

In the code sample above, Hotcakes will output the text found in the Value field of your localization file, if it exists in the right place, with the right file name, and provided your Name field matches what you put into your view.  It's worth nothing that the Name is also case sensitive.  An added trick to note is that if your Name doesn't contain any periods, the localization feature will assume that it needs to put .Text at the end of the Name, which is why your existing keys work without it.