Localization Studio Tutorial
This tutorial will demonstrate how Localization Studio can facilitate process of internationalization and localization of typical web application.
ProDinner ASP.net Awesome WebForms Sample Application will be used in this tutorial as example. It is build upon Asp.Net 3.5 and it is already localized to a few languages. In this tutorial we'll show how to:
- Find user text, that remained non-localized (hard-coded in source code)
- View translation status of resources for existing languages
- Add translations in another language
- Generate fake translations
Important: Internally Localization Studio uses MS Build software to load .NET sources. In order to open Web or Database projects you need to install appropriate version of Visual Studio (2010 or 2012). Otherwise there will be no required targets in MS Build folder and therefore such projects won't be able to load correctly.
You can download resulting localized version of Prodinner app with created Localization Solution created in this tutorial by clicking on one of the links below:
Create New Localization Solution
Let's start from creation of new Localization Solution file
- Open Localization Studio and select File -> New Solution
- Enter desired name and click Save
Tip: It is recommended to store .locsln file in the same directory where you .NET solutions stored or in the parent directory. Localization Solution file is version-control ready and stores relative paths to added projects and solutions.
As you can see Localization Studio has the same Solution Explorer as Visual Studio does. Also there is Solution Properties tab opened for newly created solution. It suggests to select base culture for the project. Base culture is essentially a language of the text which is hard-coded in source files or stored in culture-neutral
Solution Explorer show that created solution is empty and there is no source code to work with, so we need to add it. Let's add .NET solution of Prodinner sample application:
- Select File -> Add -> .NET Solution
- Select ProdinnerWebForms.sln solution file
Search Localizable Literals
Let's open Default.aspx file and check what literals does it have.
All localizable literals are highlighted using red font with yellow background. Those are literals that considered to be localizable. Those who aren't localizable (ignored) are highlighted with black font and gray background. Ignored literals aren't included in literals count shown using blue font near every tree node in Solution Explorer.
Now if we take a look at what literals are considered to be localizable by Localization Studio, it'll appear that all of them are html attributes like (class, id, style, etc) that, however enclosed in double quotes, cannot contain any user text. This means that they must be ignored. In order to do this we need to tell localization studio that those literals are non-localizable. It can be done by creating a set of rules that will "filter out" them.
The best way to spot non-localizable literals is to inspect it's usage context. For example if we'd place cursor on value of
class attribute of
div element we'd see that it's usage context is
div class which is displayed in status panel at the bottom of source code editor.
You can see that there is Ignore Context button enabled at the top panel. Upon click in opens Create Rule dialog with Context field predefined with
div class value. When saved this rule will mark all literals that are value of
class attribute of
div element as non-localizable. But there are whole bunch of other html elements that can have this attribute. There is no need to create rule for different elements. Rule Context field supports wildcards such as asterisk which represents any symbol at any repetitions (make sure to hover mouse pointer over that help icon next to Context field to see full list of supported wildcard symbols)
Apart from ignoring literals by usage context literals can also be ignored using full match (Literal field) or regex pattern (Regex field) that are applied to literal's text. However ignoring by usage context is considered to be most-effective and should be used wherever it's possible.
Global Rule Scope indicates, that rule is applicable to all projects within Localization Solution.
Project rule scope indicates that rule is applicable only within a particular project.
Once rule is created Default.aspx file's source code is re-parsed and all
class attributes of div elements are ignored. Literal count indicators will also be updated in Solution Explorer because created rule will be applied to all aspx files of all projects within localization solution.
After all non-user text attributes are ignored, it appears that there are no localizable literals. And overall count of localizable literals within Prodinner application is reduced to 309.
You can see a list of created rules by either selecting View -> Global Rules or by pressing Ctrl + Alt + G key combination. Rule editor allows to create custom rules as well as changing or deleting existing ones.
Ignore Literal in C# Files
Now let's see how we an filter-out literals in C# files. Open Model\Db.cs file. This file has 61 literal and all of them are just for setting properties of test data.
Ignore Context option is also available here. Following rules were created in order to filter out all of them:
All remaining source files can be processed in the same manner. Ignore Context is the best option to filter out literals that are 100% non-localizable. Since Prodinner application already localized only11 literals remained after all non-user text was filtered-out by appropriated rules.
Now let's see how Localization Studio can be used to facilitate process of translation of application into another language.Let's start from viewing all localized resources and theirs translation status for each supported language. Select Resources -> Analyze Translation Status
Resource Translation Analyzer allows to see translation status of each resource in application. Fake Translation status means that resource value is identical to invariant value.
Add Another Language
Now let's try and add support for German language. Suppose there is a German translator which can translate our application into German. Localization Studio allows to export all resources to Excel file which can then ca be given to translator to fill translations.
To export resources to excel file select Resources -> Export Translations to Excel
Add German culture to the list of output language and click Export button. Resulting Excel file will look like shown in screenshot below.
Translators fills out translations and sends us this excel file back.
Now all we need to to is import this file back into application. Select Resources -> Import From Excel
Click Import and check Solution Explorer. Mui.de.resx file is added to App_GlobalResources folder.
This .resx file is added to ProDinnerWebForms.csproj file. You can open it in Visual Studio and ensure that inclusion is correct.
All we have to to now is to add German option to language selection control
Generating Fake Translations
Sometimes there is need to test whether or not all localizable literals were indeed moved to resource files or whether or not application html markup is ready to display text that is different is length or height than original source text. In case when translations are not yet available, Localization Studio allows to generate fake translations which represent an original text with added prefix that contains name of the source culture. To open Translations Generator select Resources -> Generate Translations
In this example Japan language is selected as destination language. Click Generate button and Mui.ja.resx file will be included int ProdinnerWebForms.csproj
Translation Analyzer shows that all translations of Japan language are fake. They can be later overridden with real translations imported from Excel file.
Launch application and check the result