Creating custom locales
To use the ITextFormatter interface or any of the Date and Time widget variants, you need to create a custom ILocale implementation for each language you wish to support. You need to create custom ILocale objects if you have any other application or code that performs any sort of language-aware data formatting. ILocale serves as a central repository for language-specific knowledge of data formatting and can be shared across all applications. For more information ILocale, refer to the http://developer.brewmp.com/reference/api-all.
The c_samplelocales_app and c_samplelocales_extension examples, which are on the Brew MP website in http://developer.brewmp.com/resources with this document, can be used as a starting point for custom ILocale implementations. The c_samplelocales_app can be used to test your custom locale.
Custom locales are provided in an extension, as follows:
- Add all of the language-specific format strings, day names, month names, and so on with appropriate strings for the language you need to support.
- Determine if WSTRNCMP(), WSTRCMP(), WSTRUPPER(), and WSTRLOWER() are appropriate.
- Determine if your language requires any special line break behavior.
Create a project
- Copy the c_samplelocales_extension project and rename it, such as 'localexxx' where 'xxxx' is the language code of the language you intend to support.
- Open the .proj file in a text editor and change the name of project to match name used in step 1.
- Pick one of the existing locales to replace, or copy one of the existing locale implementations (
localedede.cor localeengb.c) as a starting point.
- Get a new ClassID from the https://brewx.qualcomm.com/classid/index.jsp .
- Save the new BREW ClassID BID file to your project directory.
Customize the localeXXX.c file
- In the new localexxxx.c file, #include the ClassID.BID file you generated, replacing the BID file used in the sample.
- In the Format global variables section, replace all of the language-specific format strings, day names, month names, and so on with appropriate strings for the new language.
- Find and rename the LocaleXXXX_New() function with the new language code. Replace the ClassID used in this function with the new ClassID. This is the routine that is called to create the locale.
- If your ILocale needs to do complex string formatting that cannot be fully expressed in the pattern language described in
AEELocale.h, you can customize the LocaleXXXX_FormatItem() routine to perform the required formatting.
- Determine if WSTRNCMP(), WSTRCMP(), WSTRUPPER(), and WSTRLOWER() are appropriate for the language you are supporting. If you're implementing an ILocale for a Latin-based language, the existing implementations may be sufficient. Otherwise, replace Locale_wstrncmp(), Locale_wstrcmp(), Locale_wstrupper(), and Locale_wstrlower() with custom implementations.
- Determine if the new language requires special line break behavior. Most Latin-based languages require lines to be broken on white space. If your new language has other line break requirements, replace the existing Locale_BreakLine() implementation with a custom implementation.
You may have renamed this file. You need to make a few changes to c_samplelocales_extension.c so your ILocale extension can call the appropriate New function to create your ILocale implementation.
- Include the BID file that contains the ClassID for the new language.
- Add an extern declaration for LocaleXXXX_New() where "XXXX" is the new language that will be supported.
- Add code to call this function in AEEClsCreateInstance() when the ClassID for the new language is passed in. Use the existing code as a reference.
- If your extension does not support German or U.K. English locales, remove the existing code that declares and calls LocaleEnGb_New() and LocaleDeDe_New().
c_samplelocales_extension.cifwith a text editor.
- Find "Sample Locales" and replace it with the name of your extension.
- Update the copyright information to something appropriate for your use.
- Using the existing SysRsc primitives as an example, add a SysRsc primitive for the new language.
- Using the existing Class primitives as an example, add a Class primitive for the new language.
- If your extension does not support German or U.K. English locales, remove these SysRsc and Class primitives. If you extension does support these locales, it is strongly recommended that you get new ClassIDs for them from the https://brewx.qualcomm.com/classid/index.jsp.
Build the project
You can compile your extension for the Simulator or for a device using Visual Studio.
Test your extension
You can modify c_samplelocales_app to test your extension. Or you can use your ILocale extension from your applications.