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 custom 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.
- 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 custom 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. Required. 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.
- 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 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:
-
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.
- Configure a localizable column. Learn more about configuring localizable columns in a separate guide: 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.
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.
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.
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.
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 query to the [SysAccountTypeLcz] localization table. "Nouveau Client" is specified in the @P5 parameter.
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.
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 query to the [SysAccountTypeLcz] localization table. "New Customer en-US" is specified in the @P5 parameter.
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.
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.
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:
- Configure Creatio to work in the file system. Learn more in a separate article: External IDEs.
- Export localizable resources to the file system using the SVN client.
- Modify the localizable resources.
- Commit the changes to the SVN repository.
Example 1
The Terrasoft.Core.Entities.EntitySchemaQuery class generates a data selection for an arbitrary language culture, i. e., a language culture that differs from the primary language culture in Creatio and additional language culture of the user.
To retrieve localizable resources for an arbitrary language culture:
- Call the SetLocalizationCultureId(Guid cultureId) method in the Terrasoft.Core.Entities.EntitySchemaQuery class instance before you retrieve data.
- Pass the language culture ID whose data you want to retrieve to the SetLocalizationCultureId(Guid cultureId) method.
When you run the code above, Creatio executes the SQL query. The @P1 parameter takes the value of the record ID ([Id]) stored in the italianCultureId variable.
Example 2
The FetchFromDB() methods of the Terrasoft.Core.Entities.Entity class let you retrieve multilingual data. View the example that uses one of the FetchFromDB() method overloads for a user that has a primary (English) and an additional (for example, French) language culture below. For example, you can use these methods in custom web service methods.
If the user that has the primary language culture (English) runs the code above, Creatio executes an SQL query to the primary [AccountType] database table. The @P1 parameter contains the "Customer" value that defines the corresponding record of the [AccountType] primary database table.
If the user that has an additional language culture (for example, French) runs the code above, Creatio executes an SQL query to the [SysAccountTypeLcz] localization table. The @P1 parameter contains the "Customer" value that defines the corresponding record of the [AccountType] primary database table. The @P2 parameter contains the ID value ([SysCultureId]) of the additional language culture from the [SysCulture] table. The value defines the corresponding record of the [SysAcountTypeLcz] localization table.
As a result, Name variable will correspond to "Customer" for a user that has an English language culture and "Client" for a user that has a French language culture.
1. Create an object
- Open the Configuration section and select a custom package to add the schema.
-
Click Add → Object in the section list toolbar.
-
Fill out the schema properties in the Object Designer.
- Set Code to "UsrLocalizableObject."
- Set Title to "LocalizableObject."
- Select "BaseEntity" in the Parent object property.
2. Add a localizable column
- Click in the context menu of theColumns node of the object structure. This opens a menu.
-
Hold the pointer over Text → click Text (50 characters) in the menu.
-
Fill out the column properties in the Object Designer.
- Set Code to "UsrName."
- Set Title to "Name."
- Select the Localizable text checkbox.
- Click Save and then Publish on the Object Designer toolbar.
Outcome of the example
As a result, the [SysUsrLocalizableObjectLcz] localization table will be created in the database. The table will store localized data for all localizable columns of the object.
Creatio includes the ContactAddress object schema. The schema column links to the AddressType lookup that contains the Name localizable column. View the table structure and relationships in the figure below.
- The [ContactAddress] database table contains the index of contact address values. Linked to the [AddressType] table via the [AddressTypeId] column.
- The [AddressType] database table contains the index of contact address types. The [Name] table column contains the index of address type values in the primary language. The [SysAddressTypeLcz] table contains values in additional languages.
- The [SysAddressTypeLcz] database system table contains the index of localizable values of contact address types. Generated automatically. Linked to the [AddressType] table via the [RecordId] column and to the [SysCulture] table via the [SysCultureId] column. The [Name] table column contains the index of localizable values of contact address types for the language culture that is specified in the [SysCultureId] column of the current table.
- The [SysCulture] system database table contains the index of language cultures.
1. Create a view object schema
- Open the Configuration section and select a custom package to add the schema.
-
Click Add → Object in the section list toolbar.
-
Fill out the schema properties in the Object Designer.
- Set Code to "UsrVwContactAddress."
- Set Title to "ContactAddressView."
- Select "BaseEntity" in the Parent object property.
-
Select the Represent Structure of Database View checkbox in the Behavior property block.
2. Add columns
-
Add a column that contains the index of contact address values in the primary language.
- Click next to the Columns node of the object structure. This opens a menu.
-
Hold the pointer over Text → click Text (50 characters) in the menu.
-
Fill out the column properties in the Object Designer.
- Set Code to "UsrAddress."
- Set Title to "Address."
-
Add a column that contains the index of contact address types in an additional language.
- Click next to the Columns node of the object structure. This opens a menu.
-
Hold the pointer over Text → click Text (50 characters) in the menu.
-
Fill out the column properties in the Object Designer.
- Set Code to "UsrAddressType."
- Set Title to "AddressType."
- Select the Localizable text checkbox.
- Click Save then Publish on the Object Designer toolbar.
3. Create views in the database
-
Create the [UsrVwContactAddress] view in the database. Execute the following SQL query to do this.
-
Create the [SysUsrVwContactAddressLcz] localizable view in the database. Execute the following SQL query to do this.
As a result, when Creatio retrieves data from the [UsrAddressType] column of the [UsrVwContactAddress] view using EntitySchemaQuery, the correct values for different languages will be displayed.
Outcome of the example
Create a custom web service that uses cookie-based authentication to verify the outcome of the example.
1. Create a Source code schema
- Open the Configuration section and select a custom package to add the schema.
-
Click Add → Source code on the section list toolbar.
-
Fill out the schema properties in the Schema Designer.
- Set Code to "UsrViewLocalizationService."
- Set Title to "UsrViewLocalizationService."
Click Apply to apply the changes.
2. Create a service class
- Add the Terrasoft.Configuration namespace in the Schema Designer.
- Add the namespaces whose data types to utilize in the class using the using directive.
- Add a class name that matches the schema name (the Code property).
- Specify the System.Web.SessionState.IReadOnlySessionState class as a parent class.
- Add the [ServiceContract] and [AspNetCompatibilityRequirements(RequirementsMode = AspNetCompatibilityRequirementsMode.Required)] attributes to the class.
3. Implement the class method
-
Implement a method that returns the index of values of contact address types and contact addresses from the created [UsrVwContactAddress] non-localizable view. Add the public string GetNonLocalizableView() class method that implements the endpoint of the custom web service. The method executes database queries using EntitySchemaQuery.
-
Implement a method that returns the index of localizable values of contact address types and contact addresses from the created [UsrVwContactAddress] localizable view. Add the public string GetLocalizableView() class method that implements the endpoint of the custom web service. The method executes database queries using EntitySchemaQuery.
View the source code of the UsrViewLocalizationService custom web service below.
Click Save then Publish on the Designer’s toolbar.
Outcome of the custom web service
As a result, Creatio will add the custom UsrViewLocalizationService web service that has the GetLocalizableView and GetNonLocalizableView endpoints.
Log in to Creatio and access the GetLocalizableView endpoint of the web service from the browser.
As a result, you will receive a selection that contains the localizable values of contact address types and contact addresses.
Access the GetNonLocalizableView endpoint of the web service from the browser.
As a result, you will receive a collection that contains the non-localizable values of contact address types and contact addresses.
The Terrasoft.Common namespace.
The Terrasoft.Common.LocalizableValue<T> class is a base class for the Terrasoft.Common.LocalizableString (displays localizable strings) and Terrasoft.Common.LocalizableImage (displays localizable images) classes that work with localizable resources.
The Terrasoft.Common.LocalizableValue<T> class is a template for localizable values of different types. It also provides methods that work with them.
Properties
Returns and sets the localizable value based on the current language culture.
Returns the flag that determines whether a localizable value of the current type exists for the current language culture.
Returns a localizable value lookup of the current instance for available language cultures.
Methods
Deletes the localizable value for available language cultures.
culture | A language culture. |
Retrieves a localizable value of the specified type for available language cultures. Depending on the throwIfNoManager parameter value, the method can throw an exception of the ItemNotFoundException type if the resource manager is not set for that localizable value.
culture | A language culture. |
throwIfNoManager | Flag that determines whether to call the ItemNotFoundException exception. |
Retrieves a localizable value of the specified type for available language cultures. If no localizable resource value is found for the specified language culture, returns the value for the primary language culture. Depending on the throwIfNoManager parameter value, the method can throw an exception of the ItemNotFoundException type if the resource manager is not set for that localizable value.
culture | A language culture. |
throwIfNoManager | Flag that determines whether to call the ItemNotFoundException exception. |
Determines whether a localizable value exists for the specified language culture.
culture | A language culture. |
Loads an index of localizable values of the specified type for all cultures defined in the global resource storage.
Sets the specified localizable value for the specified language culture.
culture | A language culture. |
value | A localizable value. |