Operations with localizable resources

Level: advanced

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:

1. Add the column to localize.

   1. Open the Configuration section and select a user-made package to add the schema.

   2. Click Add → Object or Replacing object on the section list toolbar.

      

   3. Fill out the schema properties in the Object Designer.

   4. Add the columns to localize if needed or select an existing object column.

   5. Select the Localizable text checkbox in the General property block of the corresponding column.

      

      note

      You can localize the following column types:

      • Text (50 characters)
      • Text (250 characters)
      • Text (500 characters)
      • Unlimited length text

   6. Click Save then Publish on the Object Designer toolbar.

2. 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:

1. Open the Configuration section and select a user-made package to add the schema.

2. 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.

     

3. Fill out the schema properties in the Designer.

4. Add the string to localize.

   1. Click the button in the context menu of the Localizable strings node.

   2. 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.

      

   3. Click Add to add a localizable string.

5. 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 in a separate article: 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:

1. 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 for View) that indicates that the schema is a view in the database.

2. Configure a localizable column. Learn more about configuring localizable columns in a separate guide: Add a localizable column.

3. 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.

Important

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 the Entity 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.

Example that saves localizable resources using a parameter of the string type

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.

SQL query

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.

Example that saves localizable resources using a parameter of the string type

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:

1. 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 query

   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='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''

2. SQL query to the [SysAccountTypeLcz] localization table. "Nouveau Client" is specified in the @P5 parameter.

   SQL query

   exec 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.

Example that saves localizable resources using a parameter of the LocalizableString type

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:

1. SQL query to the primary [AccountType] database table "Neuer Kunde de-DE" is specified in the @P2 parameter.

   SQL query

   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(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''

2. SQL query to the [SysAccountTypeLcz] localization table. "New Customer en-US" is specified in the @P5 parameter.

   SQL query

   exec 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.

Example that turns off receiving localizable resources

/* 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.

SQL query

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 in a separate article: 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 in a separate article: 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 in a separate article: 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:

1. Configure Creatio to work in the file system. Learn more in a separate article: External IDEs.
2. Export localizable resources to the file system using the SVN client.
3. Modify the localizable resources.
4. Commit the changes to the SVN repository.

Important

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

Creatio IDE

Packages basics

Version control in Subversion

Version control in Creatio IDE

External IDEs

Localize UI via the Translation section (user documentation)

Data access through ORM

---

Resources

Official TortoiseSVN website