Localization (L10N)

Luban provides several localization capabilities that can be combined:

1. datetime time zone (--timeZone)
2. text type validation (whether the key exists in the text table)
3. Static replacement (replace keys with a language’s copy at generation time)
4. Field variants (see variants)

If -x l10n.provider=... is not set, both text validation and static localization are disabled.

Text table (DefaultTextProvider)

Logically equivalent to a table of “key + one column per language”:

key	zh	en
item.gold.name	金币	Gold
item.potion.name	药水	Potion

You may use Excel or json and similar formats (must follow Luban data source rules). For json with multiple records in one file, the path must include *@:

-x l10n.provider=default
-x l10n.textFile.path=*@Datas/l10n/texts.json
-x l10n.textFile.keyFieldName=key

Parameter	Description
l10n.provider	e.g. default; omit to disable text-related features
l10n.textFile.path	Path to text data; for json lists use *@file.json
l10n.textFile.keyFieldName	Key field name, e.g. key

For key-existence validation only, language columns are optional; static replacement needs language columns.

texts.json sketch

[
  { "key": "item.gold.name", "zh": "金币", "en": "Gold" },
  { "key": "item.potion.name", "zh": "药水", "en": "Potion" }
]

text type (keys in config)

text is syntactic sugar for string#text=1. The field semantics are a localization key, not the final display string.

<bean name="Item">
  <var name="id" type="int"/>
  <var name="name" type="text"/>
</bean>

##var	id	name
##type	int	text
	1001	item.gold.name
	1002	item.potion.name

Enable validation (key must appear in the text table):

-x l10n.provider=default ^
-x l10n.textFile.path=*@Datas/l10n/texts.json ^
-x l10n.textFile.keyFieldName=key

Static replacement (key → copy at generation time)

On top of the validation options, specify the language column and turn on conversion:

-x l10n.provider=default ^
-x l10n.textFile.path=*@Datas/l10n/texts.json ^
-x l10n.textFile.keyFieldName=key ^
-x l10n.textFile.languageFieldName=zh ^
-x l10n.convertTextKeyToValue=1

After export, the name field is directly “金币”; runtime no longer needs a lookup. Suitable for builds where the language is fixed at packaging time.

(l10n.languageFieldName and l10n.textFile.languageFieldName may be interchangeable in some versions; see Cascading options.)

datetime time zone

datetime is interpreted in the target time zone and written as UTC seconds. Defaults to the local time zone; set with --timeZone:

--timeZone "Asia/Shanghai"
# On Windows you can also use:
--timeZone "China Standard Time"

Note: the short option -t is target, not time zone.

Export a list of keys to translate

Use dataTarget text-list to collect all text keys that appear in config:

dotnet Luban.dll --conf luban.conf -t all -d text-list ^
  --validationFailAsError ^
  -x outputDataDir=../Output/text ^
  -x l10n.textListFile=texts.txt

Choosing vs variants

Need	Prefer
Long copy, translation workflow, key reuse	text + text table
Same number/short field with different regional values, fixed at export	variants
Time interpreted by region only	--timeZone

Common pitfalls

• Forgetting the *@ prefix on a json text table → load failure.
• Using text fields without setting l10n.provider → validation silently off, bad keys ship.
• Static replacement without languageFieldName / convertTextKeyToValue → keys are still exported.
• Maintaining the same copy in both variants and text tables → hard to keep in sync.

Related links

• variants
• Cascading options
• Validators