Falcon Space. Localization

Introduction

Localization is used on 2 levels:

  • Interface-translation of program interface labels (for example, universal permanent labels, button names, messages in components that are stored in JS resource files instead of in the database).
  • Data - business data for the project (products, categories, pages). Translation is done for data in DB tables (what is stored in tables as rows).

To enable/disable the language mode, you must set the as_getLayoutInfo parameter enableLang = 1.

interface Localization

To localize the interface, use placemarks from the table as_langText

Note.

  1. Use the partCode for the unification of the labels in a group (it optimizes the caching of labels). For the most common tags, leave the partCode empty. A good way to set it up is depending on the page code in the form of pg{Code}, e.g. pgCatalog
  2. You don't need to do any additional manipulations in the database to extract it.
  3. In the interface, we use tags via HTML helper Lang
  4. In JS files, we use the dictionary from/js/as/controls/localization/resource{lang}.js

Data localization

To localize a certain table (in the example as_menu), additional tables are used. Each such table has its own data table named as_lang_{tableName}.

tableName is the name of the corresponding table for which we want to implement localization (it contains string columns that are analogous to the primary table, the rows in it have values for different languages for these fields)

Example:

 

  • The name and title fields are the fields of the as_menu table that we need to translate (i.e. there can be any number of fields).
  • The itemID field is an identifier in the main table (as_menu).

In the business logic request, we specify the following code (we expect that @langID int came at the entrance to the procedure):

ALTER PROCEDURE procedure [dbo].[as_getMenu]
 @roles nvarchar(256),
 @langID int = 0
AS
BEGIN
     select m.id,
		   isnull(lm.name, m.name) as name,
		   m.url,
		   m.pattern,
		   m.parentID,
		   isnull(lm.title,m.title) as title,
		   m.preTitle,
		   m.cssclass,
		   m.ord
	  from as_menu m
	  left join as_lang_menu lm on lm.itemID = m.id  and langID = @langID
	  where   [dbo].[sec_hasAccessByUsersRoles]  (@username, '', m.roles) = '1'
		and (@username<>''  and isnull(isNotAuthMenu, '0')='0' or @username=''
                and isNotAuthMenu='1')

Note how we extract the value of the text field (via isnull-we take either the language field, or if there is none, the default field and the main table)

Also note that we do left join with the as_lang_{tableName} table under 2 conditions (langID and itemID).

It is highly recommended to adhere to this localization scheme - this will simplify project maintenance in the future. 

Initial filling in of data for language tables

To do this, create a procedure like the one below with the name as_lang_{tableName}_createTexts.

It will create the missing elements for the language.  

ALTER PROCEDURE procedure [dbo].[as_lang_menu_createTexts]
 @lang nvarchar(16)
AS
BEGIN
    declare @langID int
    select @langID = id from as_langs where code = @lang

    insert into as_lang_menu (itemID, langID, name, title)
    select id, @langID, name, title
    from as_menu
    where id not in (select itemID from as_lang_menu where [langID] = @langID)

END

Passing the langID parameter to stored procedures.

In most cases, you can take the langID from the as_users table by @username.

In some cases, the language parameter will be passed directly to the stored procedure as langID.

Localization management for various entities (products, menus, etc.)

Entities are translated using the universal form for translating individual fields to different languages.

There is an entity (entityCode) that has fields.

To make it possible to translate an entity field into different languages, you must add a universal language editing form for the field.

<a href="#" class="as-form-modal btn btn-success" data-code="langField" data-itemid="page_1054_title"><i class="fa fa-language" aria-hidden="true"></i></a>

itemID is {entityCode}_{entityID}_{fieldCode}

For the new entity, you need to implement improvements to the procedures (for example, the page entity): for the table fieldLangValues stored procedures GetItems and UpdateField (write in them the logic for saving fields for pages).

This way, a similar link to the modal form is added for each field that needs to be translated into languages.

How to use localization at different levels

If you need to use a string constant that must be localized to other languages, use the features listed below:

  • If you are editing the View, use @Html.Lang(code, defValue, partCode)
  • If you are editing in Controller, use mng.Lang.GetText(code, defValue, partCode)
  • If you are editing in SQL, use the dbo.as_lang ('code', 'defaultValue', 'partCode', @langID)
  • If you are editing JS, use as.lang(code, defaultValue)

How to use localization in breadcrumbs

In the stored procedure, we use @langID extracted from @urlParameters and the dbo.as_lang function. See the example:

How to set the language immediately on the first visit

To do this, pass the link with the language code - the parameter lang=en-us.

For example, https://falcon.web-automation.ru/?lang=en-us

You can also force the language to be set in the GetLayout procedure parameter SELECT 1 - defaultLang

How to localize lists catalogs

The special langID parameter is passed to the search procedure in the @filters parameter. 

You can pass an optional additional @parameters parameter of the DictionaryParameter type to the getItem procedure, which also passes the langID. 

Notes when implementing localization

Solving problems when implementing localization: 

  1. It is better to write Large text with markup in Notepad++ with HTML syntax highlighting and showing all special characters.
  2. It is Recommended to replace the space from the text (apparently due to the insertion from Google Translate) with a space inserted from the keyboard via Ctrl + H (otherwise it is treated as   in the markup)
  3. Large layout blocks can be translated via Google Translate (but make sure that the paths to images and files are not broken). 
  4. Make sure to use the Green buttons for entity localization controls (modal form langField with a nested table fieldLangValues)
  5. Do not replace one language with another. This can cause failures in the system the scripts in translation. If you need a different language by default, replace it in GetLayout.