localization

Multiple localization mechanisms are supported and they can be used simultaneously.

Features

The following types of localization are supported:

• Time localization. Convert the datetime type data in the configuration into UTC seconds according to the specified region
• text type. A dedicated type that expresses localized string keys and can verify the validity of the keys.
• Static localization. Convert the localized key string to the corresponding actual language value when exporting to avoid the trouble of re-conversion at runtime
• Field variants. Configure a variant field for each localization target of the field, and only export the data of the specified variant when exporting

Basic concepts

ITextProvider

tip

If the -x l10n.textProviderFile=xxx parameter is not provided, text validity checking and static localization will be automatically disabled.

ITextProvider is used to provide a valid text mapping table so that TextValidator can check the validity of the localization key. Use -x l10n.provider=xxx to specify that you use ITextProvider, default corresponds to DefaultTextProvider. You can also implement your own TextProvider.

DefaultTextProvider

Use -x l10n.textFile.path=xxx to specify the localized key-value file. DefaultTextProvider uses builtin DataLoader to read data in localized files. DefaultTextProvider assumes the table format is as follows:

<bean name="TextInfo">
   <var name="{key}" type="string"/>
   <var name="{language1}" type="string"/>
   <var name="{language2}" type="string"/>
   ...
</bean>
<table name="TbTextInfo" value="TextInfo" input="xxx"/>

{key} and {languege_xxx} are custom values, for example, {key} takes key, {language_x} takes zh, en and so on.

If you only perform text verification, you do not need fields such as {langauge_xx}. Luban only uses the {key} field to verify the validity of the key.

The localized data file can be in excel format, or in a format such as json or xml, as long as it conforms to the format standard of luban's builtin DataLoader (see [excel format] (excel) and [non-excel format] (otherdatasource) documents) That’s it. When using json format, since it is impossible to put only one text data in a json file, in practice, the json file will contain a text list, and a composite data file format can be used (see [non-excel format] (otherdatasource)) fill. The following is a sample localized text table in json format. Specify the text list to be read through -x l10.textFile.path=*@your_text_file.json.

danger

When the localized string file is in a format such as json, since one file contains multiple localized data, *@ must be added before the localized file, such as *@your_text_file.json, otherwise there will be a loading error!

Time localization

Datetime type data will output the UTC seconds of the corresponding moment according to the target time zone, which is convenient for program use. The default time zone used is the local time zone, which can be used through the command line Parameter --timeZone or -t to specify the target time zone.

The time zone is the time zone name under Linux or Win, for example: -t "Asia/Shanghai" or -t "China Standard Time" specifies that the target time zone is Shanghai, Asia (that is, Beijing time)

text type

Due to the extensive localization needs, the text type is specially provided to support corresponding needs. text is a special syntactic sugar, not an independent type. It is equivalent to string#text=1, which is a string containing text=1 tag type.

Text semantically corresponds to the key of the localized string. Luban will check the validity of this key in the data validator.

You must set and specify the parameters l10n.provider, l10n.textFile.path, and l10n.textFile.keyFieldName to enable text verification. Examples are as follows:

   -x l10n.provider=default ^
   -x "l10n.textFile.path=*@D:\workspace2\luban_examples\DataTables\Datas\l10n\texts.json" ^
   -x l10n.textFile.keyFieldName=key

Static localization

Static localization will convert the text type from key to actual text value during the export process, which is suitable for occasions where the localization language has been fixed. Users no longer need to convert keys into actual documents, making it more convenient to use.

l10n.provider, l10n.textFile.path, l10n.textFile.keyFieldName, l10n.textFile.languageFieldName, l10n.convertTextKeyToValue must be set Only these parameters will enable static localization. Examples are as follows:

   -x l10n.provider=default ^
   -x "l10n.textFile.path=*@D:\workspace2\luban_examples\DataTables\Datas\l10n\texts.json" ^
   -x l10n.textFile.keyFieldName=key ^
   -x l10n.textFile.languageFieldName=zh ^
   -x l10n.convertTextKeyToValue=1

Field variants

See Field variants for details.

Collect a list of all texts in the configuration table

Sometimes you want to collect all localized text keys in the configuration. DataTarget text-list is used for this purpose. text-list will collect all text data that appears in the configuration table, sort it from small to large, and then output the file. Specify the output file through the l10n.textListFile option. For details, see the Command Line Tools document.

An example command is as follows:

dotnet Luban.dll -t all -d text-list ^
--conf D:\workspace2\luban_examples\DataTables\luban.conf ^
--validationFailAsError ^
-x outputDataDir=D:\workspace2\luban_examples\Projects\GenerateDatas\text ^
-x l10n.textListFile=texts.txt