Scope: managed applications, mobile applications, and ordinary applications.
1. If configuration modules contain strings used in the user interface (user messages, form labels, command names and tooltips, expressions in DCS settings, and so on), ensure that these strings can be localized.
To do this, use the NStr function instead of using string literals directly. Any other use of user interface strings is not allowed.
ShowMessageBox(, "To execute the operation, install a file system extension.");
ShowMessageBox(, NStr("en="To execute the operation, install a file system extension."));
You also need to make sure that the NStr function is used correctly.
MessageText= "en="To execute the operation, install a file system extension."; ShowMessageBox(, NStr(MessageText));
MessageText = NStr("en='To execute the operation, install a file system extension.'"); ShowMessageBox(, MessageText);
2. If a string is complex and includes parts that depend on certain conditions, you need to use logically complete and whole phrases or sentences. Use the StrTemplate function or the similar one to insert parameters into user message strings.
Firstly, this requirement is because parameters are located differently in a sentence in different languages and you need to change the source code to rearrange available string snippets. Secondly, it will be impossible to correctly translate separate mismatching sentence parts (availability or absence of articles and prepositions, different punctuation in a sentence in different languages, and so on).
ShortageMessage = "Not enough goods " + GoodsName + " in warehouse " + WarehouseName + ".";
MessageText = NStr("en = "Not enough goods %1 in warehouse %2.");
ShortageMessage = StrTemplate(MessageText, GoodsName, WarehouseName);
Do not use insert parameters to break a whole phrase into separate logically incomplete parts. Instead, specify several strings with all phrase options in the code.
NStr("en = "%1 user ""%2"" in group ""%3""?") // where the %1 parameter can be "Include", "Copy", or "Delete".
NStr("en = "Include user ""%2"" in group ""%3""?")
NStr("en = "Copy user ""%2"" to group ""%3""?'")
NStr("en = "Delete user ""%2"" in group ""%3""?")
It is allowed to:
- Compose texts from several sentences. Each sentence is enclosed in NStr and translated separately.
- End sentences with a colon. For example, NStr("en = "Cannot create the catalog due to:").
In accordance with established practice, you can use named insert parameters (parameters that include names and not numbers similarly to variables) only in two options: [Parameter] and %Parameter%. Here, the Parameter must meet requirements of the Naming variables standard.
ShortageMessage = NStr("en="Not enough goods %Goods% in warehouse %Warehouse%.") ShortageMessage = StrReplace(ShortageMessage, "%Goods%", GoodsName); ShortageMessage = StrReplace(ShortageMessage, "%Warehouse%", WarehouseName);
3. If Standard Subsystems Library is used in the configuration, in complex formatted strings, use the FormattedStringfunction of the StringFunctionsorStringFunctionsClient common modules instead of the FormattedString object.
Text = New Array; Text.Add(NStr("en = "Before deleting an extension, it is recommended")); Text.Add(" "); Text.Add(New FormattedString(NStr("en = "that you back up the infobase."), StyleFonts.BoldFont); WarningText = New FormattedString(Text);
WarningText = StringFunctionsClient.FormattedString(NStr("en = "Before deleting an extension, it is recommended <b>that you back up the infobase</b>.");
4. In the NStr function, each string is enclosed in single quotes. This requirement is due to frequent use of double quotes in string literals as well as due to mechanism of editing strings in different languages that is integrated into the platform.
ShowMessageBox(, NStr("en="Variable of the ""String" type")); ShowMessageBox(, NStr("en=""Variable of the ""String" type""));
ShowMessageBox(, NStr("en="Variable of the ""String" type"));
AmountInWords = NumberInWords(2341.56, "L = en_EN; DE = True", NStr("en="dollar,dollars,m,cent,cents,m,2"));
AmountInWords = NumberInWords(2341.56, "DE = True", NStr("en="dollar,dollars,m,cent,cents,m,2"));
6. Sometimes, for example, when you need to compose a long message with a user action log, you can combine strings instead of replacing them in a template string. Include non-language characters (most often, line breaks) at the beginning and at the end of strings in separate string literals, which are omitted upon translation.
MessageText = NStr("en = "Cannot save the document file due to: |") + ErrorInfo;
MessageText = NStr("en = "Cannot save the document file due to:") + Chars.LF + ErrorInfo;
Otherwise, when translating a string into another language, a space at the end might be omitted by a translator as they do not see the whole context but only a summary table of strings to be translated. The translator might distort a phrase as they do not see its continuation and there is no insert template character indicating that this sentence it to be continued.
7. As the infobase can be accessed by users speaking different languages, autogenerated strings that are written to the infobase programmatically and are visible to users are to be displayed in the default configuration language rather than in the language of the current user.
For example, an automatically generated comment to posting, the EventName parameter of the WriteLogEvent method.
Make sure that such strings can be localized and explicitly define the main configuration language for them. Otherwise, if multi-language configurations are used and a document is posted by a user with Russian interface and then the same document is re-posted by a user with English interface, content of accounting register entries changes, which is incorrect.
It is recommended that you add comments to such places in the code that explain a reason for exception to the rule:
Comment = NStr("en = "Comment to posting", Metadata.MainLanguage.LanguageCode); // The string is saved to the infobase
If Standard Subsystems Library is used in the configuration, to get a code of the main language, use the DefaultLanguageCode function of the Common or CommonClient common module.
8. When you call the ShowQueryBox method and specify dialog box buttons in the Buttons parameter:
• When possible, use the DialogReturnCode system enumeration.
• If an enumeration does not contain the needed button, in addition to a value related to the button, define its presentation using the NStr function.
Buttons = New ValueList; Buttons.Add("Disable"); Buttons.Add("No"); ShowQueryBox(..., Buttons);
Buttons = New ValueList; Buttons.Add("Disable", NStr("en="Disable")); Buttons.Add(DialogReturnCode.No); ShowQueryBox(..., Buttons);