Internationalization and Code Generation

Internationalization support in software development tooling is vital to enabling efficient globalization. If there is a remote possibility that you could collaborate in the future with others across locales, consider internationalization from project inception. Internationalization can prevent rework or having to develop a new model design. The relevant requirement concerns locale settings.

Locale Settings

On a computer, a locale setting defines the language (character set encoding) for the user interface and the display formats for information such as time, date, and currency. The encoding dictates the number of characters that a locale can render. For example, the US-ASCII coded character set (codeset) defines 128 characters. A Unicode^® codeset, such as UTF-8, defines more than 1,100,000 characters.

For code generation, the locale setting determines the character set encoding of generated file content. To avoid garbled text or incorrectly displayed characters, the locale setting for your MATLAB^® session must be compatible with the setting for your compiler and operating system. For information on finding and changing the operating system setting, see Internationalization or see the operating system documentation.

Prepare to Generate Code for Mixed Languages and Locales

To prepare to generate code for a model, identify:

The operating system locale.
The locale of the MATLAB session.
Code generation requirements for:
- Target Language Compiler files
- Code generation template files that include comments (requires Embedded Coder^®)

Character Set Limitations

Target language compiler files support user default encoding only. To produce international, custom generated code that is portable, use the 7-bit ASCII character set.

XML Escape Sequence Replacements

The code generator replaces characters that are not represented in the character set encoding of a model with XML escape sequences. Escape sequence replacements occur for block, signal, and Stateflow^® object names that appear in:

Generated code comments
Code generation reports
Block paths logged to MAT-files
Block paths logged to C API files model_capi.c (or .cpp) and model_capi.h

CGT Files and XML Escape Sequence Replacements

The code generator replaces characters that are not represented in the character set encoding for a model with XML escape sequences. Escape sequence replacements occur for block, signal, and Stateflow object names that appear in Comments in code generation template (CGT) files.

By default, code generation template files do not contain character set encoding information. The operating system reads the files, using its current encoding, regardless of the encoding that you use to write the file. You can enable escape sequence replacements by adding the following token at the top of the template file:

<encodingIn = "encoding">

Replace encoding with a string that names a standard character encoding scheme, such as UTF-8, ISO-8859–1, or windows-1251.

For an example, open example file MixedLanguagesAndLocales.cgt.

openExample('ecoder/CodeWithMixedLanguagesAndLocalesECExample',...
'supportingFile','MixedLanguagesAndLocales.cgt')

This example shows content from the file MixedLanguagesAndLocales.cgt in a MATLAB session for windows-1251. The encodingIn token sets the encoding to UTF–8, which is the correct value for code generation.

Generate and Review C Code with Mixed Languages and Mixed Locales

This example uses:

Open Script

This example shows how to use the code generator to produce and review C code for use in mixed languages and mixed locales.

Before using this example, see Internationalization and Code Generation or Internationalization and Code Generation.

The configuration for model MixedLanguagesAndLocales uses system target file ert.tlc. To see internationalization and localization support with Simulink® Coder™, configure the model to use the grt.tlc system target file. The example indicates the support that is specific to Embedded Coder (for example, code generation templates).

The model configuration specifies files and settings that control how the code generator handles localization for:

C API interfaces
Code generation template (CGT) files (requires Embedded Coder)
Target Language Compiler (TLC) files that apply code customizations (requires Embedded Coder)

Open Example Model

Open example model MixedLanguagesAndLocales. Labels in the model appear in multiple languages (Arabic, Chinese, English, German, and Japanese) and various Unicode symbols.

model = 'MixedLanguagesAndLocales';
open_system(model);

Open Embedded Coder App

In the Apps tab, select Embedded Coder.

Verify Locale Settings

Verify that the locale setting for your MATLAB® software is compatible with your compiler. See the documentation for your operating system.

Configure Code Generation Template File

To use a code generation template file with unicode characters when generating code, complete these steps (requires Embedded Coder). Otherwise, go to the next section.

1. Open the Configuration Parameters dialog box.

2. Navigate to the Code Generation > Template pane. The model is configured to use the code generation template file MixedLanguagesAndLocales.cgt. That file adds comments to the top of generated code files. For the code generator to apply escape sequence replacements for the .cgt file, enable replacements by specifying:

<encodingIn = "encoding-name">

3. Open the file MixedLanguagesAndLocales.cgt.

edit MixedLanguagesAndLocales.cgt

4. Find the line of code that enables escape sequence replacements for the character set encoding UTF-8.

<encodingIn = "UTF-8">

5. Close the file MixedLanguagesAndLocales.cgt.

Configure Code Customization File

To use file customization templates with unicode characters when generating code, complete these steps (requires Embedded Coder). Otherwise, go to the next section.

You can specify customizations to generated code files by using TLC code. TLC files support user default encoding only. To produce international custom generated code that is portable, use the 7-bit ASCII character set.

1. Open the Configuration Parameters dialog box.

2. Navigate to the Code Generation > Template pane. The model is configured to use the code customization file example_file_process.tlc. That file customizes the generated code just before the code generator writes the code files. For example, the file adds a C source file, corresponding include file, and #define and #include statements.

3. Open the file example_file_process.tlc.

edit example_file_process.tlc

4. Before generating code, check that the following line of code is uncommented:

assign ERTCustomFileTest = TLC_TRUE

5. Close the file example_file_process.tlc.

Generate C Code and Report

1. Configure the model for C code generation. Then, generate C code and a code generation report. Set model configuration parameter Language to C. Alternatively, in the Command Window, type:

set_param(model,'TargetLang','C');

2. Generate C code and a code generation report.

evalc('slbuild(model)');

Review Generated Code

Use the code generation report to review the generated code. For characters that are not in the current MATLAB character set encoding, the code generator uses escape sequence replacements to render characters correctly in the code generation report.

1. If the code generation report for model MixedLanguagesAndLocales is not open, in the Command Window, type:

coder.report.open(model);

2. Review the generated code in MixedLanguagesAndLocales.c and MixedLanguagesAndLocales.h. Names of model elements appear in code comments as replacement names in the local language.

3. Open the Traceability Report. The report maintains traceability information, even when the name contains characters that are not represented in the current encoding. Names of model elements appear in the report as replacement names in the local language.

4. Scroll down to and click the code location link for the first Chart (State 'Selection' <S2>:23). The report view changes to show the corresponding code in MixedLanguagesAndLocales.c.

5. In the code comment, click the <S2>:23 link. The model window shows the chart in a new tab.

6. In the model window, right-click that chart. From the context menu, select C/C++ Code > Navigate to C/C++ Code. The report view changes to show the named constant section of code for that chart.

7. Close the code generation report, Model Advisor, and model. In the Command Window, type:

coder.report.close();
bdclose(model);

Generate and Review C++ Code with Mixed Languages and Mixed Locales

This example uses:

Open Script

This example shows how to use the code generator to produce and review C++ code for use in mixed languages and mixed locales.

Before using this example, see Internationalization and Code Generation or Internationalization and Code Generation.

The model configuration specifies files and settings that control how the code generator handles localization for:

C++ API interfaces
Code generation template (CGT) files (requires Embedded Coder)
Target Language Compiler (TLC) files that apply code customizations (requires Embedded Coder)

Open Example Model

Open example model MixedLanguagesAndLocales. Labels in the model appear in multiple languages (Arabic, Chinese, English, German, and Japanese) and various Unicode symbols.

model = 'MixedLanguagesAndLocales';
open_system(model);

Open Embedded Coder App

In the Apps tab, select Embedded Coder.

Verify Locale Settings

Verify that the locale setting for your MATLAB® software is compatible with your compiler. See the documentation for your operating system.

Configure Code Generation Template File

To use a code generation template file with unicode characters when generating code, complete these steps (requires Embedded Coder). Otherwise, go to the next section.

1. Open the Configuration Parameters dialog box.

<encodingIn = "encoding-name">

3. Open the file MixedLanguagesAndLocales.cgt.

edit MixedLanguagesAndLocales.cgt

4. Find the line of code that enables escape sequence replacements for the character set encoding UTF-8.

<encodingIn = "UTF-8">

5. Close the file MixedLanguagesAndLocales.cgt.

Configure Code Customization File

To use file customization templates with unicode characters when generating code, complete these steps (requires Embedded Coder). Otherwise, go to the next section.

1. Open the Configuration Parameters dialog box.

3. Open the file example_file_process.tlc.

edit example_file_process.tlc

4. Before generating code, check that the following line of code is uncommented:

assign ERTCustomFileTest = TLC_TRUE

5. Close the file example_file_process.tlc.

Generate C++ Code and Report

1. Configure the model for C++ code generation. Set model configuration parameter Language to C++. If you are using Embedded Coder, by default, this parameter setting changes the setting of model configuration parameter Code interface packaging to C++ class. Alternatively, in the Command Window, type:

set_param(model,'TargetLang','C++');

2. Generate C++ code and a code generation report.

evalc('slbuild(model)');

Review Generated Code

1. If the code generation report for model MixedLanguagesAndLocales is not open, in the Command Window, type:

coder.report.open(model);

2. Review the generated code in MixedLanguagesAndLocales.c and MixedLanguagesAndLocales.h. Names of model elements appear in code comments as replacement names in the local language.

3. If you are using Embedded Coder, open the Traceability Report. The report maintains traceability information, even when the name contains characters that are not represented in the current encoding. Names of model elements appear in the report as replacement names in the local language.

4. Scroll down to and click the code location link for the first Chart (State 'Selection' <S2>:23). The report view changes to show the corresponding code in MixedLanguagesAndLocales.c.

5. In the code comment, click the <S2>:23 link. The model window shows the chart in a new tab.

7. Close the code generation report, Model Advisor, and model. In the Command Window, type:

coder.report.close();
bdclose(model);