Almost every user interface application needs to support many different languages. Embedded Wizard Studio and the programming language Chora provides a couple of clever features to facilitate the development of multi-lingual applications.
This article will guide you through the different aspects like string management, string table import and language selection. The following sample application will demonstrate the usage of an Excel sheet string table and the language change during runtime.
The source code of the 'StringTable' sample (including an Excel sheet template) is installed with your Embedded Wizard Studio installation - just open the example.
Execute a WebGL version of the 'StringTable' demo.
Languages
Within an Embedded Wizard project the different user languages are represented and identified by different language bricks, e.g. 'German', 'French' or 'Japanese'. During the creation of an UI object, all used resources and constants are evaluated on existing language variants, in order to realize multilingual content.
Resources and constants can be filled with different values for each language variant. If the language is switched, the corresponding value of the language variant is loaded. It should be mentioned that an existing GUI object will not immediately change its appearance, because the language variants are checked only during the creation of an object. For those classes who should change their appearance immediately, Embedded Wizard offers the attribute Multilingual. This attribute causes Embedded Wizard to generate additional code to perform an immediate re-initialization for a new user language.
The most common language variant is the string constant. Of course, it is possible to define the language dependent content of all string constants directly within Embedded Wizard Studio - but this will be a painful work.
In order to maintain all your strings in a comfortable way, it is quite customary, to collect and store language variants of the required string within an Excel sheet during development. This makes it easy to exchange the document between the developers and the different translator offices that might be necessary.
String generation
The basic idea of the provided example is, to generate a unit file – which is nothing else than a readable text file with a certain defined syntax – from an Excel sheet, converting the sheet’s content into EmWi compatible constants thereby.
The unit 'Strings' of the provided example contains 7 string constants with multilingual values, representing the 7 days of the week. Additionally 9 string constants for the supported languages are present in the table, but only with the value for the Default-language.
The unit 'Strings' – or the file Strings.ewu more precisely – was generated by an Excel macro. This macro is implemented in Visual Basic Script and stored in the Excel sheet. You will find the file Strings.xls included in the project directory.
The Excel sheet consists of two pages. The first page is 'StringTable'. It lists in the first row the language variant identifiers, in the first column the string IDs and collects all language variant values for the string IDs. At least the default language must be implemented to avoid a Chora compiler error. The default name for the generated *.ewu file is always the name of the Excel file with the extension 'ewu' e.g.: Strings.xls becomes Strings.ewu.
Note: Don’t use unit names that can conflict with standard C-libraries (string.h) because each unit generates a '*.c' and '*.h' module that must be compiled and linked with your project.
If a string contains the new line characters '\n', it will cause a new line in a Views::Text object without displaying the '\n'. If a backslash should be displayed in Embedded Wizard, it must be entered as '\\'.
In the second page 'Generator', the user can adapt the value 'No of Languages' (columns of StringTable) and the value 'No of Constants' (rows of the StringTable). A click on the Generator button starts the conversion process.
The intention of this Excel sheet is to provide a simple example, which can be used as it is, but also it can easily be copied and/or modified. It is very easy to change e.g. the formatting of the generated ewu-file or add some functionality. In general this Excel sheet is not a tool for Embedded Wizard, but a template to make the translation of strings easier and independent from an Embedded Wizard license. By this way an external translation office can do the translations totally independent from the development.
Example Project
The unit 'Application' of the sample project contains the class Application::Application with 7 text views to display the 7 weekday strings. For demonstration purpose, the application contains 9 buttons which changes the currently active language of the user interface.
The unit 'Strings' contains all the generated strings from the Excel sheet. Each time you generate the *.ewu file again, Embedded Wizard will show the following message. A double click on this message will reload the unit.
Font Range calculation
If you open the 'Generator' page of the Excel sheet Strings.xls, you will see a further button 'Generate Font Range'.
The Excel macro related to this button will report all used characters from the page 'StringTable'. As a result, the file 'FontRange.txt' is generated. You can use the given ranges from this file to limit the character codes of your font resources to the absolute minimum: Only those characters are converted by the Font Converter, that are really necessary for your UI project. This is very useful to save code memory (ROM/Flash).
Please note: The font range generation makes only sense if the range of characters is predictable! For displaying dynamic content an additional fix range of characters can be defined. If you don’t want to include a default range, just leave these cells empty.
Another hurdle for the automatic font range generation might be, if you have different fonts using different font ranges. In this case you have to adapt the Excel macro up to your requirements or define the different fonts in different copies of the Excel files.
