How to configure in what language the given user sees data in the user interface of an 1C:Enterprise platform Infobase configuration in different modes?
You develop a 1C:Enterprise Infobase configuration for a customer from another country.
This customer has several user groups. And members of each of these groups can have a specific language/locale. This means that users from different groups can have different language environments.
Computers of your developers implementing the project for the customer can also have a language/locale that does not match that of the customer's user groups.
The goal for your developers is to ensure that in the application they develop:
- customer's end users can see only text in the language they know;
- neither of customer's end users can see text in the language they do not know.
To reach this goal, you need to:
- know how 1C:Enterprise platform's language and locale parameters affect the language-specific behavior of the configuration (information representation, data language, and so on);
- configure the working environments of your developers properly;
- localize the appropriate parts of the application according to the described methodology;
- prepare instructions on how to configure the working environments of your customer's end users.
We will consider different scenarios how end users work the application:
- thin/thick client
- web client
- mobile application
Language, locale, and other software localization-specific terms
Before describing how localization in different languages is supported in 1C:Enterprise platform-based solutions, let us recall the main terms related to software localization.
Language is a collection of properties used in spoken and written communication between humans.
According to World Wide Web Consortium (W3C), localization is adapting the content of a product, software program or documentation to language mappings, cultural and other requirements of a target market (a locale).
Typically, localization includes the adaptation of the following scope areas:
- Case mapping
- Numerical formats
- Date and time formats
- Currency formats
- Collation (sorting)
- Symbols, signs, and colors
- Text and graphical images whose content is related to objects, action or idea that can be interpreted incorrectly or with indifference in the given cultural environment
- Different legal requirements
- And many others
Internationalization stands for creating and developing the content of a product, software program or documentation to enable their easy localization for target markets that differ by culture, region or language.
On an operating system, a language itself is indicated by language code like "en" for English, "de" for German, "fr" for French, and so on. Language codes are defined by ISO 639 (https://www.iso.org/iso-639-language-codes.html), an international standard that assigns two- and three-letter codes to most languages of the world.
A language is just part of a locale. For instance, "de" as the language code does not tell you where German is spoken. In the countries that use German as an official language, they have different sorting order, different number formats, and so on. In other words, language is not always sufficient to precisely define a locale.
For each country, there is a country code. Country codes are defined by ISO 3166, another international standard. It assigns two- and three-letter abbreviations for each country in the world. In contrast to the language codes, country codes are set uppercase. For instance, "CA" for Canada, "FR" for France, "US" for the USA.
As you may guess, a more geographically specific language (a locale) can be indicated by the language code and the country code. For instance, "fr-CA" is the locale having the French language in Canada.
We can say that a locale is a collection of language-related user preference information.
Each operating system has at least one installed locale and often has other locales from which the user can select.
1C:Enteprise platform enables you not only to create and run applications in different languages (localization support), but also to quickly introduce new languages for your target applications (internationalization support). For more information, refer to https://1c-dn.com/1c_enterprise/internationalization/
User interface elements: what comes from where?
Let us recall how the internationalization support mechanism is organized in 1C:Enterprise.
The main two sources of language-specific resources are 1C:Enterprise platform and your configuration.
The platform provides a list of supported languages. For each language, once it is installed in your environment, the language-specific resources that come with 1C:Enterprise platform (say, error messages, system message boxes, and so on) are available in the application you develop and run there. For more information, see https://1c-dn.com/1c_enterprise/platform_interface_languages/.
The list of these resources is rather huge. Let us put it simply:
- standard UI resources that come from the platform
- standard images that come from the platform
As for your configuration, here we can describe the resources in more detail:
- your configuration's UI resources to be translated in Designer (synonyms, titles, and so on)
- your configuration's NStr-encoded UI resources
- your configuration's templates
- your configuration-specific images
In general, the approach of localizing these resources is described here: https://1c-dn.com/1c_enterprise/interface_text_editor/.
Now you know what resources you can control in your configuration to make them appear in your application. The other resources that come to your application appear there from the platform. (Once a language is supported in the platform, all platform-specific resources in the language are available in your applications.)
The auxiliary sources of language-specific resources are as follows:
- system message boxes
- system dialog boxes (like the Open File dialog box)
- web browser's message boxes
- web browser's dialog boxes
- DBMS-specific message boxes
Configuration localization requirements
In a nutshell, the methodology of localizing your application is as follows:
- Make sure that all the languages you want to see in the customer's configuration are supported in 1C:Enterprise platform and installed in your environment.
- In the configuration, specify all the languages you want to support there and ensure you have the language-specific resources translated to all these languages.
- Make sure that the database in DBMS supports the target locale.
- Make sure that the operating system's current user works in the target locale.
User interface strings - localization requirements
If in your configuration you have strings to be displayed in the user interface (like messages for users, form captions, names and hints of commands, expressions in settings of Data Composition System), you should provide the capability of localizing these strings.
For this purpose, use the
NStr() function instead of direct usage of string literals. The latter is prohibited.
ShowMessageBox(, "To perform this operation, install extension for work with files.");
ShowMessageBox(, NStr("en='To perform this operation, install the extension for work with files.'");
ShowMessageBox(, NStr("en='To perform this operation, install the extension for work with files.'; de='Um diesen Vorgang durchzufuhren, installieren Sie die Erweiterung fur die Arbeit mit Dateien.'");
Also, pay attention how to use the
NStr() function correctly:
MessageText="en='To perform this operation, install the extension for work with files.'";
MessageText=NStr("en='To perform this operation, install the extension for work with files.'");
The system can automatically generate strings, store them to the Infobase, and display them for users via the user interface.
As users who speak different languages can work with the same Infobase, these strings may need displaying in the configuration's default language, rather than in the current user's language.
For instance, the automatically generated comment for an accounting transaction, the
EventName parameter of the
For such strings, you should provide their localized representation, but specify the configuration's default language for them explicitly. Otherwise, when working in a multi-language configuration, if a user having the English user interface commits a transaction and afterward a user with the French user interface commits the transaction anew, then the content of the accounting registry records gets changed, which is not acceptable.
You should document such pieces of code with comments that clarify the reason you used
NStr() not according to the rules described above.
Comment = NStr("en = 'Transaction comment'", ConfigurationMetadataObject.DefaultLanguage.LanguageCode); // the string is written to the infobase
Forms - localization requirements
For attributes used as forms' elements, it is forbidden to use non-localized strings. For these attributes, it is recommended to use either value lists where for each value you specify its localized representation (via the ChoiceList property), or enumerations (if they are used in database tables).
When working with a value list, always enable its ListChoiceMode property. In this instance, the system correctly displays the localized representation for the corresponding list item instead of the selected list item's value.
Templates - localization requirements
If in your configuration you use binary templates to store data that requires a translation when it is used in another language (templates, for short), then, in the template name, specify the following postfix:
"_" and the language code as it is specified in the metadata.
For instance, "_de" for the German language specified in the Language code property.
The following is an example of a template name:
In your code, depending on the language, use the template with the corresponding postfix:
... = GetCommonTemplate("ODT_Invoice");
... = GetCommonTemplate("ODT_Invoice" + "_" + CurrentLanguage());
If in your code you need to get data from a table-, text- or HTML-based template with the language that differs from that of the current user, use the
LanguageCode property (for
SpreadsheetDocument) or the
TemplateLanguageCode property (for
For instance, when you generate a printed form in a language that differs that of the current user:
Template = GetCommonTemplate("PrintedForm");
Template.TemplateLanguageCode = "de";
HTMLDocument = Template.GetHTMLDocument();
Dates - localization requirements
When using the
Format() function, you should take into account that in different countries different date component sequences and delimiters are used.
For instance, the same date (20 December 2017) is represented in different ways: 2017-12-20 for Germany, 12/20/2012 for the USA.
So, instead of specifying the date directly:
you should use the local date format:
When you specify date formats in controls of forms and fields of reports based on Data Composition System, you should also use local date formats. The same requirement is valid when you redefine the standard representation of fields in such reports.
How the system detects language and locale for user interface elements?
When using 1C:Enterprise Infobase's configuration, the system determines the language to apply to the configuration and to the platform separately and the locale to apply to the entire application.
Detecting configuration language
To detect the configuration's language, the system takes the following language sources into account (from highest to lowest priority):
- user's language specified in the configuration
- default language specified in the configuration
So, when running your application, by default (if no user is defined in your Infobase or no language is specified for the user) the system uses the configuration's default language to display the configuration-specific data of your application. If there is a language specified for the user in the Infobase, the system uses this language display the configuration-specific data of your application.
Also, once the system detects the configuration language according to the method described above, it applies it by default to the following pieces of code:
This means that if in your configuration you have, for instance, a call to the
NStr() function where no language is specified directly or the
SpreadsheetDocument.LanguageCode property with the undefined value, the system uses the configuration language detected for them.
As you can see, it is quite simple for the configuration. Though, is it is a bit more sophisticated for the platform.
Detecting platform language
To detect the platform's language of a client application, the system takes the following language sources into account (from highest to lowest priority):
- language launching parameters for the client application
SystemLanguageparameter of 1C:Enterprise platform's conf.cfg file
- 1C:Enterprise platform's *.res file
- operating system's current user's language
Shortly, if there is a launching parameter that points to an existing platform language, the system uses this language to display the client application's platform-specific data. If there is no such a parameter or the parameter points to an unavailable platform language, the system uses the language defined in the
SystemLanguage parameter of the conf.cfg file to display the client application's platform-specific data. If conf.cfg file does not resolve the platform language explicitly, the system uses the *.res file to detect the platform language. If the platform language remains undetected even here, the system uses operating system's current user's language to display the client application's platform-specific data.
To learn how the system detects the platform's language of the web client, see Web client: specifying platform's user interface language.
Detecting application locale
The locale determines the way how your application displays Boolean, numerical, and date/time values and how it sorts string lists. Once the locale is detected, it is applied to the entire application: both to the platform- and configuration-specific data.
To detect the application locale of a client application, the system takes the following locale sources into account (from highest to lowest priority):
- locale launching parameters for the client application
- Infobase locale and regional settings
- operating system's current user's locale
Shortly, if there is a launching parameter that points to an existing locale, the system uses this locale to display the client application's data. If there is no such a parameter or the parameter points to an unavailable locale, the system uses the Infobase locale to display the client application's data provided that the Use regional settings of the current session option is disabled for the Infobase locale. If the Use regional settings of the current session option is enabled for the Infobase locale, the system uses operating system's current user's locale to display the client application's data.
In any case, by default the system applies operating system's current user's locale to the following functions:
This means that if in your configuration you have, for instance, a call to the
NumberInWords() function where no locale is specified directly, the system uses operating system's current user's locale in the call.
To learn how the system detects the application locale of the web client, see Web client: specifying user interface locale.
As you can see, there is no way to say the system to display this user interface element in one language and another element in another language. If you fulfilled the localization methodology requirements described here for your application, and then you run the application on behalf of the given user on the given operating system via the given client type, you can separately set the language of the platform, the language of the configuration, and the locale for the entire application.
Client application: specifying the platform language via launching parameter
To explicitly specify the language of 1C:Enterprise platform for a particular client application via the language launching parameter, do any of the following:
- In Designer, from the Tools menu, select Options, then click the 1C:Enterprise startup tab, click the Additional tab, then, from the Platform interface language dropdown listbox, select the language with which you want to run 1C:Enterprise platform for the client application.
- Use the "/L" command-line parameter to set the code of the language with which you want to run 1C:Enterprise platform for the client application. For instance, "/LEN" makes 1C:Enterprise platform run in English.
SystemLanguage parameter in conf.cfg file
SystemLanguage parameter of 1C:Enterprise platform's conf.cfg file sets the platform language to apply.
As the value of the parameter, you can either specify the "System" value, or specify one of the following codes of the languages supported in the platform:
- az - Azerbaijani
- en - English
- bg - Bulgarian
- hu - Hungarian
- vi - Vietnamese
- ka - Georgian
- zh - Chinese
- lv - Latvian
- lt - Lithuanian
- de - German
- pl - Polish
- ro - Romanian
- ru - Russian
- tr - Turkish
- uk - Ukrainian
- fr - French
If you set the "System" value for the parameter, the system uses the language of the current user of the operating system as the platform language.
If you set a particular language code as the value of the parameter, the system uses this language as the platform language. For instance:
If you set a language code of a non-existent or not installed localization of the platform, the system tries to use the language of the current user of the operating system as the platform language. If no platform localization in this language is installed, the system uses the English language as the platform language.
When using your client application on Windows, pay attention to the following peculiarities:
- If the conf.cfg file with the platform language specified resides in the conf directory of a particular version of 1C:Enterprise platform, the system applies the specified language to the given platform version only.
- If the conf.cfg file with the platform language specified resides in the C:\Program Files\1cv8\conf directory, the system applies the specified language to all platform versions installed on the computer.
If the conf.cfg file contains no
SystemLanguage parameter, the system detects the platform language via the *.res file. Once 1C:Enterprise platform is installed, the *.res file is to be created automatically in the configuration file folder where conf.cfg file resides. Alternatively, you can create the appropriate *.res file manually. The name of the file coincides with the code of the platform language installed. For instance, "en.res" for English. The contents of the *.res file does not matter. The system only takes the file's name into account.
If there is no *.res file, then, when starting your application, the system uses the language of the current user of the operating system as the platform language. In the name of the *.res file, specifying the language code of a non-existent or not installed localization of the platform is equal to the situation when there no *.res file.
Client application: specifying the locale via launching parameter
To explicitly specify the locale for a particular client application via the locale launching parameter, do any of the following:
- In Designer, from the Tools menu, select Options, then click the 1C:Enterprise startup tab, click the Additional tab, then, from the Session locale code dropdown listbox, select the locale you want to run your client application with.
- Use the "/VL" command-line parameter to set the code of the locale you want to run your client application with. For instance, "/VLen_US" makes your application run with the English locale settings accepted in the United States.
Infobase locale and regional settings
The locale of the given Infobase is specified when creating the Infobase. If you need to change the locale of an existing Infobase, in Designer, from the Administration menu, select Regional Infobase settings, and then, from the Language (country) dropdown list box, select an appropriate locale for the Infobase.
From the First day of the week dropdown list box, select an appropriate day to be the first day of the week throughout the Infobase. If the "Auto" value is selected, the system automatically selects the first day of the week in accordance with the locale you selected in the Language (country) dropdown list box.
If the Use regional settings of the current session option is disabled and no other parameters except for Language (country) and First day of the week are specified, then date/time and numerical representation formats are determined with the default settings specified in 1C:Enterprise platform for the given locale while Boolean (logical) values are determined with the language applied to the platform. This makes date/time and numerical representation formats identical for all users connected to the Infobase. Of course, you can also specify these settings as well as Boolean values directly for the entire Infobase.
If users from different countries work with the Infobase, it is often preferable to let each of the users see dates, times, numbers, and Boolean values according to the format accepted in their language and country (locale). In this instance, enable the Use regional settings of the current session option. If no locale is specified explicitly for the given session, the data of the application is displayed according to the regional settings specified for the user in the operating system.
Additionally, Infobase's regional settings affect the built-in calendar and the string sorting order. Users can call the built-in calendar by selecting Calendar from the Service menu. The system uses it as a control for editing values of fields of the data type. You can address to the calendar from forms by using the CalendarField control. When displaying the calendar, the system always uses infobase's regional settings.
How the developer can check languages that affect user interface elements?
Here are the language-related parameters you can address to from your code:
Current = CurrentLanguage();
A calculated parameter. Equals to the user interface language specified for the current user in the configuration. If there is no current user in the configuration or there is no language specified for this user, equals to the default language of the configuration. This is a universal approach to address the current language in your configuration.
UserLanguage = InfoBaseUsers.CurrentUser().Language.LanguageCode;
Code of the language specified directly for the current user in your configuration.
ConfDefaultLanguage = ConfigurationMetadataObject.DefaultLanguage.LanguageCode;
Code of the default language specified directly for your configuration. This is a way to set this language and the capability to check against it from your application code.
Current system language
Infobase locale code
InfobaseLocalization = InfoBaseLocaleCode();
Code of the locale specified for the given Infobase upon its creation.
SystemCurrent = CurrentSystemLanguage();
A calculated parameter. Equals to the operating system's language.
Error message localization
If when running your application based on 1C:Enterprise platform the system encounters an error related to incorrect usage of the script in your application, it displays an error message. In the error message, there are three parts:
- Name of the module where the error occurred
For instance, "SessionModule".
- Error description
For instance, "Procedure or function with the specified name is not defined".
- Name of the script item (function, procedure or property) where the error occurred
For instance, "MyFunction".
The system separately determines the language to display each of these error message parts.
As for the module name, the system uses the value of the "Script Variant" configuration property. For this property, you can select one of the following two values: "English" and "Russian". Thus, the name of the erroneous module is displayed either in English or in Russian.
The error description is displayed in the language with which the system runs the platform when running your application. For more information, refer to Detecting platform language.
As for the script item name, the system always uses the language in which the script item is written. So, if you write your script in English, then the names of your script's functions, procedures or properties you see in these error messages are always in English.
Web client: localization specifics
1C:Enterprise platform supports the following web browsers for applications running in web client mode:
- for Windows:
- Mozilla Firefox 38 or later;
- Microsoft Internet Explorer 10.0-11.0;
- Microsoft Edge;
- Google Chrome 4 or later (32- and 64-bit versions). When working in a 64-bit version, the browser uses 32-bit versions of extensions and external components.
- for Linux:
- Mozilla Firefox 38 or later;
- for Mac OS X 10.5 or later:
- Safari 4.0.5 or later.
- for iOS 3.2 or later (on iPad)
- Safari 4.528.16 or later
Internet Explorer - language-specific settings
When working with the web client in Microsoft Internet Explorer, every time the user opens an additional window or tab, the operating system applies the keyboard layout according to its setting. If this keyboard layout does not correspond to the language the user wants to enter data in, the user has to switch to another language manually. To avoid language switching for the user, you can set an appropriate language in the user's operating system.
To do this, perform the following (description is given for Microsoft Windows 7):
- On Windows, click Start > Control Panel.
- Click Clock, Language, and Region, and then click Regional and Language Options.
NOTE If you do not see Clock, Language, and Region, click Category in the View by menu at the top of the page.
- In the Regional and Language Options dialog box, in the Languages and Keyboards tab, click Change Keyboards.
- In the Text Services and Input Languages dialog box, on the General tab, under Default input language, click the language that you want to use as the default language.
- Click OK.
- Click OK.
Mozilla Firefox - language-specific settings
If the user interface of 1C:Enterprise platform installed on your application's server has the language that differs from the language of Mozilla Firefox, then to ensure correct work of the web client in this web browser, perform the following steps:
- In Mozilla Firefox, on the menu, click Options.
- On the General tab, in the Fonts & Colors section, click Advanced.
- In the dialog box, enable Allow pages to choose their own fonts, instead of your selections above, then, under Fallback Text Encoding, select Default for Current Locale, and click OK.
- On the General tab, in the Language section, click Choose.
- In the dialog box, add all languages you want to use in Mozilla Firefox to the list, arrange them in the order of preference (the most preferable language is on top), and click OK.
Google Chrome - language-specific settings
If the user interface of 1C:Enterprise platform installed on your application's server has the language that differs from the language of Google Chrome, then to ensure correct work of the web client in this web browser, perform the following steps:
- In Google Chrome, on the menu, click Settings.
- Click Advanced and then expand the Languages section.
- Add all languages you want to use in Google Chrome to the Order languages based on your preference list and arrange them in the order of preference (the most preferable language is on top).
Safari - language-specific settings
In the Safari web browser, the user interface language of the web client equals to the language of the web browser unless the web client's language is specified directly via the "L" launching parameter.
Web client: specifying platform's user interface language
In the web client, you can specify the language of 1C:Enterprise platform as follows (from highest to lowest priority):
- the "L" launching parameter in the browser's address bar
- web browser's preferable language setting
NOTE The platform language affects what Boolean (logical) values are displayed in the web client.
When selecting the user interface language, the system performs the following:
- When processing the request to the resource where the given Infobase is published (for instance, "http://localhost/demo"), the system selects the localization language.
- If the URL specified in the web browser's address bar contains the "L" parameter (for instance, "http://localhost/demo?L=en"), the system analyzes its value provided that the language is supported in the web browser's settings. If the system cannot select the language based on the parameter, it analyzes the Accept-Language HTTP heading.
- If the URL specified in the web browser's address bar contains no "L" parameter, the system analyzes the Accept-Language HTTP heading, which contains preferable languages defined in the web browser.
- The system selects an appropriate language from the list of localizations installed to the web-server.
- If no exact match is found (for instance, the parameter value is "en_US"), the system truncates the sought-for language name and searches for the language again ("en" in this example).
- If the sought-for language is not found, the system applies the default language - English ("en").
- The system appends the selected language to the application's base URL ("http://localhost/demo/en") and automatically redirects the web browser to the resulting URL.
NOTE The Safari web browser does not support the preferable language settings. Instead, for this web browser, the system applies the operating system's language.
Web client: specifying the user interface locale
In the web client, you can specify the locale, which affects the representation of numerical and date/time values, as follows (from highest to lowest priority):
- the "VL" launching parameter in the browser's address bar
- web browser's preferable language setting
When selecting the regional settings, the system performs the following:
- If the URL specified in the web browser's address bar contains the "VL" parameter, the system applies the regional settings of the locale specified in the parameter provided that the locale is supported in the web browser's settings. For instance, "http://localhost/demo?VL=en_US" makes your application to display with the English (USA) locale. The system appends the specified locale to the application's base URL ("http://localhost/demo/en_US") and automatically redirects the web browser to the resulting URL. If the "VL" parameter points to a non-existent localization, the web client returns an error message.
- If the URL specified in the web browser's address bar contains no "VL" parameter, the system analyzes the Accept-Language HTTP heading, which contains preferable languages defined in the web browser.
Mobile platform applications - localization specifics
You localize your applications whose target is 1C:Enterprise mobile platform, in the same manner, you do for desktop applications.
They are a few distinctions to consider.
Neither Android, nor iOS support changing an application's user interface language for the given application only. The sole way to change the language of your application is to change the language for the entire operating system the mobile user works with - and this changes the language for all applications there at once.
Known issues and their solutions
User's language can differ from the language defined in the application. As a result, the user can see certain data in another language.
Methods to fix
When starting your application, check in its code whether the system language of the platform and the user's language coincide and then do either of the following:
- Start 1C:Enterprise platform with the command-line parameter that sets the language to the current language.
- If the user is defined in the configuration, set the user's language to the system language. If there is no user, use method 1.