Skip to main content
Version: 8.0

Operations with localizable resources

Level: advanced

Creatio lets you execute operations with localizable resources using multiple tools:

  • Creatio IDE
  • database
  • SVN version control system
  • file system

Execute operations with localizable resources using Creatio IDE​

Add a localizable column​

Localizable columns let you display object data in multiple languages in Creatio UI. The localizable column value is based on the language chosen in the user profile. Configure a localizable column in Object Designer.

To add a localizable column:

  1. Open the Configuration section. Instructions: Open the Configuration section.

  2. Create a new schema or select an existing schema whose column to localize. Creatio lets you add a localizable column to an object schema and replacing object schema.

  3. Add a new column to localize if needed. Creatio lets you localize the following column types:

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

  4. Mark the column as localizable.

    1. Go to the General property block.

    2. Select the Localizable text checkbox.

  5. Publish the schema.

  6. Translate the localizable column value. Instructions: Localize UI via the Translation section (user documentation).

As a result, the column will include values in different languages. Creatio UI uses a value based on the language chosen in the user profile.

Add a localizable string​

Localizable strings let you display module data in multiple languages in Creatio UI. The localizable string value is based on the language chosen in the user profile. Configure a localizable string in the Module Designer and Source Code Designer.

To add a localizable string:

  1. Open the Configuration section. Instructions: Open the Configuration section.

  2. Create a new schema or select an existing schema whose string to localize. Creatio lets you localize strings of the following schema types:

    • Module
    • Page view model
    • Section view model
    • Detail (list) view model
    • Detail (fields) view model
    • Replacing view model
    • Source code

  3. Add a new string to localize if needed. To do this, go to the Localizable strings node’s context menu → click . This opens the Localizable Strings window.

  4. Fill out the localizable string properties.

    Property

    Description

    Code*

    The localizable string name. Starts with the prefix. Can contain Latin characters and digits. Learn more: Manage configuration elements.

    Value

    The localizable string value. By default, Creatio displays the value for the language chosen in the user profile. To set the localizable string values in different languages, click .

  5. Save the localizable string. To do this, click Add.

  6. Publish the schema.

As a result, the string will include values in different languages. Creatio UI uses a value based on the language chosen in the user profile.

Execute operations with localizable resources using database​

Retrieve localizable resources from the database​

View a list of classes that let you retrieve localizable resources from the database in the table below.

Class

Description

Terrasoft.Core.Entities.EntitySchemaQuery

Retrieves data from the database via the ORM model. Supports multilingual data.

Terrasoft.Core.Entities.Entity

Works with the database entity.

Learn more about retrieving data from the database using Terrasoft.Core.Entities.EntitySchemaQuery and Terrasoft.Core.Entities.Entity classes: Data access through ORM.

Creatio generates multilingual data selection using rules listed in the table below.

Primary language

Additional language

Value of the localizable resource (the SysLocalizableValue database table)

Resulted selection

Active

Inactive

Not specified

Creatio generates data selection from the primary database table.

Inactive

Active

Specified

Creatio generates data selection from the SysLocalizableValue database table.

Inactive

Active

Not specified

Creatio generates data selection from the primary database table.

To retrieve data from localizable columns, configure localizable views. To do this:

  1. Implement an object.

    1. Add an object schema. Instructions: Implement an object. Specify the schema name (the Code property) based on the following template: [DeveloperPrefix][DatabaseViewPrefix]ObjectName. For example, UsrVwContact.
    2. Add a localizable column. Read more >>>

  2. Create a view in the database.

    1. Ensure that Id column values of the view are unique. Otherwise, it can lead to errors in the business logic that displays data, especially in Freedom UI lists and expanded lists.
    2. Execute SQL queries.

Detailed example: Localize the view in the database.

View the example that retrieves localizable resources for the Italian language that differs from primary and additional languages using the Terrasoft.Core.Entities.EntitySchemaQuery class below.

Retrieve localizable resources for the Italian language
/* The user connection. */
var userConnection = (UserConnection) HttpContext.Current.Session["UserConnection"];

/* Retrieve the ID of the needed language. */
var sysCulture = new SysCulture(userConnection);

/* Return an error message if the primary language is not found. */
if (!sysCulture.FetchPrimaryInfoFromDB("Name", "it-IT")) {
    return "No culture found";
}

/* Retrieve ID of the Italian language. */
Guid italianCultureId = sysCulture.Id;

/* Create an EntitySchemaQuery instance that has the "City" root schema. */
var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "City");

/* Add a column to the query. */
esqResult.AddColumn("Name");

/* Pass the ID of the Italian language. */
esqResult.SetLocalizationCultureId(italianCultureId);

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

When a user runs code above, Creatio executes an SQL query. The @P1 parameter matches the record ID value (Id column) stored in the italianCultureId variable.

SQL query
SELECT
    ISNULL([SysCityLcz].[Name], [City].[Name])[Name]
FROM
    [dbo].[City] [City] WITH(NOLOCK)
    LEFT OUTER JOIN [dbo].[SysCityLcz] [SysCityLcz] WITH(NOLOCK) ON ([SysCityLcz].[RecordId] = [City].[Id]
    AND [SysCityLcz].[SysCultureId] = @P1)

View the example that retrieves the localizable value of the Name column in the AccountType schema using the FetchFromDB() method of Terrasoft.Core.Entities.Entity class below. The FetchFromDB() method retrieves multilingual data and overloads for a user who has both primary and additional languages.

Retrieve localizable resources using the FetchFromDB() method
/* The user connection. */
var userConnection = (UserConnection) HttpContext.Current.Session["UserConnection"];

/* Retrieve the "Account type" schema. */
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");

/* Create the "Entity" instance. */
Entity entity = schema.CreateEntity(userConnection);

/* The collection of column names to generate a selection. */
List<string>columnNamesToFetch = new List<string>{
    "Name",
    "Description"
};

/* Retrieve object data whose "Name" column value is "Customer." */
entity.FetchFromDB("Name", "Customer", columnNamesToFetch);

/* Display the result in the language chosen in the user profile. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

When a user who has English as their primary language runs code above, Creatio executes an SQL query to the primary AccountType database table. The @P1 parameter includes the "Customer" value that defines the corresponding record of the primary AccountType database table.

SQL query
exec sp_executesql N'
SELECT
    [AccountType].[Name] [Name],
    [AccountType].[Description] [Description]
FROM
    [dbo].[AccountType] [AccountType] WITH(NOLOCK)
WHERE
    [AccountType].[Name] = @P1',N'@P1 nvarchar(6)',@P1=N'Customer'

When a user who has the additional language (French) runs code above, Creatio executes an SQL query to the localization SysAccountTypeLcz database table. The @P1 parameter includes the "Customer" value that defines the corresponding record of the primary AccountType database table. The @P2 parameter includes the ID value (SysCultureId column) of the additional language in the SysCulture database table. The value defines the corresponding record of the localization SysAccountTypeLcz database table.

SQL query
exec sp_executesql N'
SELECT
    ISNULL([SysAccountTypeLcz].[Name], [AccountType].[Name]) [Name],
    ISNULL([SysAccountTypeLcz].[Description], [AccountType].[Description]) [Description]
FROM
    [dbo].[AccountType] [AccountType] WITH(NOLOCK)
    LEFT OUTER JOIN [dbo].[SysAccountTypeLcz] [SysAccountTypeLcz] WITH(NOLOCK) ON ([SysAccountTypeLcz].[RecordId] = [AccountType].[Id]
    AND [SysAccountTypeLcz].[SysCultureId] = @P2)
WHERE
    [AccountType].[Name] = @P1',N'@P1 nvarchar(6),@P2 uniqueidentifier',@P1=N'Customer',@P2='A5420246-0A8E-E111-84A3-00155D054C03'

As a result, the Name column value will correspond to "Customer" for a user who has English as their primary language and "Client" for a user who has an additional language (French).

Update localizable resources in the database​

If you need to change the localizable resource value in the SysLocalizableValue database table, use Creatio IDE, SVN version control system, or file system. Do not add data using a direct SQL query because this does not add information about the added localizable resources to the properties of the corresponding schema.

Afterward, update localizable resources. To do this, 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, in turn, will cause the localizable resource value to be lost.

Save localizable resources to the database​

Creatio generates the name of the localization database table based on the following template: [Sys]NameOfPrimaryDatabaseTable[Lcz]. For example, SysContactTypeLcz.

To save localizable resources to the database, use the Entity.SetColumnValue() method. The method can accept parameters of both LocalizableString and string types. Unlike the LocalizableString type, the database table into which Creatio saves localizable resources using the string type parameters is determined based on the language chosen in the user profile.

Save localizable resources using parameters of the LocalizableString type​

View the example that saves German and English localizable resources using a parameter of the LocalizableString type below.

Example that saves localizable resources using a parameter of the LocalizableString type
/* The user connection. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Retrieve the "Account type" schema. */
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");

/* Create the "Entity" instance. */
Entity entity = schema.CreateEntity(userConnection);

/* Set the default column values. */
entity.SetDefColumnValues();

/* Create a localizable string that includes localized values for German and English languages. */
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 "Name" column value using the localizable string. */
entity.SetColumnValue("Name", localizableString);

/* Save the changes. */
entity.Save();

/* Display the result in the language chosen in the user profile. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

Regardless of the language chosen in the user profile, when a user runs code above, Creatio executes the following SQL queries:

  1. SQL query to the primary AccountType database table. The @P2 parameter includes the "Neuer Kunde de-DE" value of the localizable string.

    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 localization SysAccountTypeLcz database table. The @P5 parameter includes the "New Customer en-US" value of the localizable string.

    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'

As a result, when a user who has an additional language runs code above and the localizable string value is not specified for the primary language, Creatio will add the record that includes a localizable string value for the additional language to the primary AccountType table.

Save localizable resources using parameters of the string type​

Creatio saves localizable resources using the string type parameters and the rules listed in the table below.

Primary language

Additional language

User action

Saving result

Inactive

Active

Add a record

Creatio saves data to primary and localization database tables of the Entity object.

Inactive

Active

Modify a record

Creatio saves data to the localization database table of the Entity object.

Active

Inactive

Add or modify a record

Creatio saves data to the primary database table of the Entity object.

I. e., Creatio determines the database table for saving localizable resources based on the language selected in the user profile. This causes a value in the primary database table that does not match the primary language. To prevent that, save localizable resources using parameters of the LocalizableString type.

View the example that saves localizable resources using a string type parameter for a user who has German as their primary language below.

Example that saves localizable resources using a string type parameter
/* The user connection. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Retrieve the "Account type" schema. */
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");

/* Create the "Entity" instance. */
Entity entity = schema.CreateEntity(userConnection);

/* Set the default column values. */
entity.SetDefColumnValues();

/* Set the "Name" column value. */
entity.SetColumnValue("Name", "Neuer kunde");

/* Save the changes. */
entity.Save();

/* Display the result in the language chosen in the user profile. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

When a user who has German as their primary language runs code above, Creatio executes an SQL query to the primary AccountType database table. The @P2 parameter includes the "Neuer kunde" value of the localizable string.

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 string type parameter for a user who has an additional language (French) below.

Example that saves localizable resources using a string type parameter
/* The user connection. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Retrieve the "Account type" schema. */
EntitySchema schema = userConnection.EntitySchemaManager.FindInstanceByName("AccountType");

/* Create the "Entity" instance. */
Entity entity = schema.CreateEntity(userConnection);

/* Set the default column values. */
entity.SetDefColumnValues();

/* Set the "Name" column value. */
entity.SetColumnValue("Name", "Nouveau Client");

/* Save the changes. */
entity.Save();

/* Display the result in the language chosen in the user profile. */
var name = String.Format("Name: {0}", entity.GetTypedColumnValue<string>("Name"));
return name;

When a user who has an additional language (French) runs code above, Creatio executes the following SQL queries:

  1. SQL query to the primary AccountType database table. The @P2 parameter includes the "Nouveau Client" value of the localizable string.

    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 localization SysAccountTypeLcz database table. The @P5 parameter includes the "Nouveau Client" value of the localizable string.

    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'

As a result, the primary AccountType database table will include a value that does not match the primary language. To prevent that, save localizable resources using parameters of the LocalizableString type.

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 chosen in the user profile.

Example that turns off localizable resources
/* The user connection. */
var userConnection = (UserConnection)HttpContext.Current.Session["UserConnection"];

/* Create an EntitySchemaQuery instance that has the "City" root schema. */
var esqResult = new EntitySchemaQuery(userConnection.EntitySchemaManager, "City");

/* Add a column to the query. */
esqResult.AddColumn("Name");

/* Turn off receiving localizable resources. */
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 chosen in the user profile, when a user runs 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 the SVN version control system​

Creatio lets you update localizable resources from the SVN repository and commit localizable resources to the SVN repository using the SVN version control system. Creatio executes both operations together with the corresponding package operation. Instructions: Version control using the Configuration section.

Execute operations with localizable resources using file system​

Creatio lets you modify localizable resources using file system. To do this:

  1. Enable the file system development mode. Instructions: Set up Creatio to work with the file system.

  2. Download a package that includes localizable resources to the file system.

    1. Open the Configuration section. Instructions: Open the Configuration section.
    2. Click Actions → File system development mode group → Download packages to file system.

  3. Modify the localizable resources based on your business goals.

  4. Commit the changes to the SVN repository. Instructions: Instructions: Commit a package to the SVN repository.

As a result, Creatio saves the modified value of localizable resources to the database. The localizable resource value corresponds to a single record in the SysLocalizableValue database table. This record includes links to the corresponding IDs (SysPackageId, SysSchemaId, SysCultureId columns) and key (the Key column). Therefore, if you commit a localizable resource whose status is Conflicted, the database table includes the last value of the localizable resource.

See also​

Creatio IDE overview

Localize UI via the Translation section (user documentation)

Data access through ORM

Configuration elements of the Object type

Version control using the Configuration section

External IDEs basics