Operations with localizable resources
To execute operations with localizable resources, you can use the following tools:
- Creatio IDE
- database
- SVN version control system
- file system
Execute operations with localizable resources using Creatio IDE
You can execute the following operations with localizable resources using Creatio IDE:
- add a localizable column
- add a localizable string
Add a localizable column
Localizable columns let you display object data in multiple languages in Creatio UI. The localizable column value depends on the language selected in the user profile. You can configure a localizable column in the Object Designer. The database stores the column value.
To add a localizable column:
-
Add the column to localize.
-
Open the Configuration section and select a user-made package to add the schema.
-
Click Add → Object or Replacing object on the section list toolbar.
-
Fill out the schema properties in the Object Designer.
-
Add the columns to localize if needed or select an existing object column.
-
Select the Localizable text checkbox in the General property block of the corresponding column.
noteYou can localize the following column types:
- Text (50 characters)
- Text (250 characters)
- Text (500 characters)
- Unlimited length text
-
Click Save then Publish on the Object Designer toolbar.
-
-
Translate the localizable column value. To do this, follow the instruction in the user documentation: Localize UI via the Translation section.
As a result, the column will contain values in different languages. Creatio UI uses a value that depends on the language selected in the user profile.
Add a localizable string
The localizable string lets you display module data in multiple languages in Creatio UI. The localizable string value depends on the language selected in the user profile. You can configure a localizable string in the Module Designer and Source Code Designer. The database stores the string value.
To add a localizable string:
-
Open the Configuration section and select a user-made package to add the schema.
-
Click Add on the section list toolbar and select the schema type.
-
Select one of the following options if you want to localize the Client Module string:
- Module
- Page view model
- Section view model
- Detail (list) view model
- Detail (fields) view model
- Replacing view model
-
If you want to localize the Source Code string, select Source code.
-
-
Fill out the schema properties in the Designer.
-
Add the string to localize.
-
Click the button in the context menu of the Localizable strings node.
-
Fill out the localizable string properties:
- Enter the localizable string name in the Code* property. Must start with the prefix specified in the Prefix for object name (SchemaNamePrefix code) system setting,
Usr
by default. - Enter the localizable string value in the Value property. By default, Creatio saves the value for the language selected in the user profile. Click the button to set the localizable string values in different languages.
- Enter the localizable string name in the Code* property. Must start with the prefix specified in the Prefix for object name (SchemaNamePrefix code) system setting,
-
Click Add to add a localizable string.
-
-
Click Save then Publish on the Designer toolbar.
As a result, the string will contain values in different languages. Creatio UI uses a value that depends on the language selected in the user profile.
Execute operations with localizable resources using the database
You can execute the following operations with localizable resources using the database:
- retrieve localizable resources from the database
- update localizable resources in the database
- save localizable resources to the database
- disable localizable resources in the database
Retrieve localizable resources from the database
The following classes implement the mechanism that retrieves localizable resources from the database:
Terrasoft.Core.Entities.EntitySchemaQuery
. Retrieves data from the database via the ORM model. Supports multilingual data by default.Terrasoft.Core.Entities.Entity
. Works with the database entity.
Learn more about retrieving data from the database using the Terrasoft.Core.Entities.EntitySchemaQuery
and Terrasoft.Core.Entities.Entity
classes: Data access through ORM.
The rules to generate a selection of multilingual data are as follows:
- if a primary language is active in the user profile, the data selection is generated from the primary database table.
- if an additional language is active in the user profile and the value of the localizable resource exists in the
[SysLocalizableValue]
database table, the data selection is generated from the[SysLocalizableValue]
database table. - if an additional language is active in the user profile and the value of the localizable resource does not exist in the
[SysLocalizableValue]
database table, the data selection is generated from the primary database table.
To generate a data selection, you can use views
that let you retrieve data from localizable columns. Configure localizable views to generate a selection of localizable data using a view.
To configure localizable views:
-
Create an object schema for the view. Use the following schema name template:
UsrVwObjectSchemaName
.The schema name must contain the following required elements:
- First prefix specified in the Prefix for object name (SchemaNamePrefix code) system setting,
Usr
by default. - Second
Vw
prefix (short forView
) that indicates that the schema is a view in the database.
- First prefix specified in the Prefix for object name (SchemaNamePrefix code) system setting,
-
Configure a localizable column. Learn more about configuring localizable columns: Add a localizable column.
-
Add a localization view to the database.
Update localizable resources in the database
Update localizable resources when the localizable resource value in the [SysLocalizableValue]
database table is changed.
To update the localizable resources in the database for the corresponding schema, modify the [IsChanged]
column value of the [SysPackageResourceChecksum]
database table using an SQL query. Otherwise, a localizable resource conflict will occur when the package is updated in Creatio. The conflict cannot be detected, which will cause the localizable resource value to be lost.
Do not add data to the [SysLocalizableValue]
database table using a direct SQL query because this does not add information about the added localizable resources to the metadata of the corresponding schema. To add localizable resources, use Creatio IDE, SVN version control system, or file system.
Save localizable resources to the database
To save localizable resources, use the Entity.SetColumnValue()
method. The method can accept parameters of the string
and LocalizableString
types.
Save localizable resources using parameters of the string
type
The special features of saving localizable resources using parameters of the string
type are as follows:
- if a user that has an additional language adds a record, Creatio saves data to the primary table of the
Entity
object and localization table of theEntity
object - if a user that has an additional language modifies a record, Creatio saves data to the localization table of the
Entity
object - if a user that has a primary language adds or modifies a record, Creatio saves data to the primary table of the
Entity
object
Creatio generates the localization table name based on the following template: [SysPrimaryTableNameLcz]
.
View the example that saves localizable resources using a parameter of the string
type for a user that has a primary language (German) below.
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");
Entity entity = schema.CreateEntity(userConnection);
/* Set the default column values. */
entity.SetDefColumnValues();
/* Set the [Name] column value. */
entity.SetColumnValue("Name", "Neuer kunde");
/* Save. */
entity.Save();
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;
If the user that has the primary language (German) runs the code above, Creatio executes an SQL query to the primary [AccountType]
database table. "Neuer kunde" is specified in the @P2
parameter.
exec sp_executesql N'
INSERT INTO [dbo].[AccountType]([Id], [Name], [CreatedOn], [CreatedById], [ModifiedOn], [ModifiedById], [ProcessListeners], [Description])
VALUES(@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8)',N'@P1 uniqueidentifier,@P2 nvarchar(12),@P3 datetime2(7),@P4 uniqueidentifier,@P5 datetime2(7),@P6 uniqueidentifier,@P7 int,@P8 nvarchar(4000)',@P1='3A820BC8-006D-42B7-A472-E331FBD73E20',@P2=N'Neuer kunde',@P3='2021-09-20 09:40:23.0909251',@P4='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P5='2021-09-20 09:40:23.0929256',@P6='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P7=0,@P8=N''
View the example that saves localizable resources using a parameter of the string
type for a user that has an additional language, for example, French, below.
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");
Entity entity = schema.CreateEntity(userConnection);
entity.SetDefColumnValues();
entity.SetColumnValue("Name", "Nouveau Client");
entity.Save();
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;
If the user that has an additional language, for example, French, runs the code above, Creatio executes the following SQL queries:
-
SQL query to the primary
[AccountType]
database table. The query is similar to the query for the primary localization, but "Nouveau Client" is specified in the@P2
parameter.SQL queryexec sp_executesql N'
INSERT INTO [dbo].[AccountType]([Id], [Name], [CreatedOn], [CreatedById], [ModifiedOn], [ModifiedById], [ProcessListeners], [Description])
VALUES(@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8)',N'@P1 uniqueidentifier,@P2 nvarchar(12),@P3 datetime2(7),@P4 uniqueidentifier,@P5 datetime2(7),@P6 uniqueidentifier,@P7 int,@P8 nvarchar(4000)',@P1='94052A88-499D-4072-A28A-6771815446FD',@P2=N'Nouveau Client',@P3='2021-09-20 10:07:00.3454424',@P4='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P5='2021-09-20 10:07:00.3454424',@P6='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P7=0,@P8=N'' -
SQL query to the
[SysAccountTypeLcz]
localization table. "Nouveau Client" is specified in the@P5
parameter.SQL queryexec sp_executesql N'
INSERT INTO [dbo].[SysAccountTypeLcz]([Id], [ModifiedOn], [RecordId], [SysCultureId], [Name]) VALUES(@P1, @P2, @P3, @P4, @P5)',N'@P1 uniqueidentifier,@P2 datetime2(7),@P3 uniqueidentifier,@P4 uniqueidentifier,@P5 nvarchar(12)',@P1='911A721A-0E5A-4CC3-B6D9-9E5FE85FEC64',@P2='2021-09-20 10:07:00.3664442',@P3='94052A88-499D-4072-A28A-6771815446FD',@P4='A5420246-0A8E-E111-84A3-00155D054C03',@P5=N'Nouveau Client'
Therefore, the primary [AccountType]
table will contain a value that does not match the primary localization. To prevent that, save localizable resources using parameters of the LocalizableString
type.
Save localizable resources using parameters of the LocalizableString
type
View the example that saves localizable resources using a parameter of the LocalizableString
type below.
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");
Entity entity = schema.CreateEntity(userConnection);
entity.SetDefColumnValues();
/* Create a localizable string that contains localized values for different language cultures. */
var localizableString = new LocalizableString();
localizableString.SetCultureValue(new CultureInfo("de-DE"), "Neuer Kunde de-DE");
localizableString.SetCultureValue(new CultureInfo("en-US"), "New Customer en-US");
/* Set the column value using the localizable string. */
entity.SetColumnValue("Name", localizableString);
entity.Save();
/* Display the result in the current language culture of the user. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;
Regardless of the language selected in the user profile, if the user runs the code above, Creatio executes the following SQL queries:
-
SQL query to the primary
[AccountType]
database table "Neuer Kunde de-DE" is specified in the@P2
parameter.SQL queryexec sp_executesql N'
INSERT INTO [dbo].[AccountType]([Id], [Name], [CreatedOn], [CreatedById], [ModifiedOn], [ModifiedById], [ProcessListeners], [Description])
VALUES(@P1, @P2, @P3, @P4, @P5, @P6, @P7, @P8)',N'@P1 uniqueidentifier,@P2 nvarchar(18),@P3 datetime2(7),@P4 uniqueidentifier,@P5 datetime2(7),@P6 uniqueidentifier,@P7 int,@P8 nvarchar(4000)',@P1='5AC81E4A-FCB2-4019-AE5B-0C485A5F65BD',@P2=N'Neuer Kunde de-DE',@P3='2021-09-20 10:47:21.7471581',@P4='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P5='2021-09-20 10:47:21.7511578',@P6='410006E1-CA4E-4502-A9EC-E54D922D2C00',@P7=0,@P8=N'' -
SQL query to the
[SysAccountTypeLcz]
localization table. "New Customer en-US" is specified in the@P5
parameter.SQL queryexec sp_executesql N'
INSERT INTO [dbo].[SysAccountTypeLcz]([Id], [ModifiedOn], [RecordId], [SysCultureId], [Name])
VALUES(@P1, @P2, @P3, @P4, @P5)',N'@P1 uniqueidentifier,@P2 datetime2(7),@P3 uniqueidentifier,@P4 uniqueidentifier,@P5 nvarchar(18)',@P1='6EC9C205-7F8B-455E-BC68-3D9AA6D7B7C0',@P2='2021-09-20 10:47:21.9272674',@P3='5AC81E4A-FCB2-4019-AE5B-0C485A5F65BD',@P4='A5420246-0A8E-E111-84A3-00155D054C03',@P5=N'New Customer en-US'
If the user that has an additional language executes the code above and the localizable string value does not exist for the primary language, Creatio adds the record that contains additional language value to the primary [AccountType]
table.
Turn off localizable resources in the database
To turn off localizable resources, set the UseLocalization
property of the EntitySchemaQuery
class instance to false
. Turning off localizable resources does not remove localizable resources from database tables and does not depend on the language in the user profile.
/* The user connection. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];
/* Generate a query. */
var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "City");
/* Add a column to the query. */
esqResult.AddColumn("Name");
/* Turn off the mechanism that selects localized data. */
esqResult.UseLocalization = false;
/* Execute a database query and retrieve the resulting object collection. */
var entities = esqResult.GetEntityCollection(userConnection);
/* Retrieve the query text. */
var s = esqResult.GetSelectQuery(userConnection).GetSqlText();
/* Return the result. */
return s;
Regardless of the language selected in the user profile, if the user runs the code above, Creatio executes an SQL query to the primary [City]
database table.
SELECT
[City].[Name] [Name]
FROM
[dbo].[City] [City] WITH(NOLOCK)
Execute operations with localizable resources using SVN version control system
You can execute the following operations with localizable resources using SVN version control system:
- update localizable resources from the SVN repository
- commit localizable resources to the SVN repository
Learn more about working with SVN: Version control in Subversion.
Update localizable resources from the SVN repository
To update localizable resources from the SVN repository, update the package from the SVN repository. Learn more about updating packages: Version control in Creatio IDE.
The available localizable resource statuses are as follows:
- modified. The localizable resource was changed.
- added. The localizable resource was added.
- deleted. The localizable resource was deleted.
- conflicted. Multiple developers worked with the localizable resource simultaneously. One developer committed localizable resource changes to the SVN repository.
Commit localizable resources to the SVN repository
To commit localizable resources to the SVN repository, commit the package to the SVN repository. Learn more about committing packages: Version control in Creatio IDE.
You can lock a package in the SVN repository using Creatio IDE. Locking a package prevents the conflicted status of the localizable resource because multiple users cannot work with the package simultaneously. For example, a developer modifies the localizable package resources without pre-locking them. Another developer can modify the same localizable resources and commit them to the SVN repository of the current package. In this case, when you commit the package to SVN and update the package, Creatio IDE displays a list of localizable resources in the conflicted status. I. e., the version and content of the localizable resources changed by the first developer do not match those of the resources committed to the SVN repository. The localizable resource changes committed to the SVN repository will be lost when you commit changes. Resolve such conflicts manually using SVN clients, for example, TortoiseSVN.
Execute operations with localizable resources using the file system
You can modify localizable resources using the file system.
To modify localizable resources from the file system:
- Configure Creatio to work in the file system. Learn more: External IDEs.
- Export localizable resources to the file system using the SVN client.
- Modify the localizable resources.
- Commit the changes to the SVN repository.
The localizable resource value corresponds to a single record from the [SysLocalizableValue]
database table. This record contains links to the appropriate IDs ([SysPackageId]
, [SysSchemaId]
, [SysCultureId]
) and key ([Key]
). Therefore, if you commit a resource whose status is conflicted, Creatio writes the last value to the table.
See also
Version control in Creatio IDE
Localize UI via the Translation section (user documentation)