让你的Mod变得"国际化"——1.4.4版

注：现在，在tml官方wiki上也有关于国际化的内容。请参考英文版或中文版

1.4.4 tml进行了本地化系统的大改，因此，1.4的很多信息已不再适用。如果在进行1.4.4的开发，可以不用阅读旧版文档。

基础

tModLoader使用hjson文件存储翻译文本。hjson的格式与json基本相同，但是有一些区别：

hjson不需要在项间添加逗号。
hjson不需要在字符串两端添加引号。
hjson可以使用注释。
hjson支持以 ”’ 包裹的多行字符串。
hjson不需要在最外层添加大括号。例如，对于

{
    "Root": {
           "First": {
            "A": "一",
            "B": "Two Second"
        },
        "The Second": {
            "C":"Three\nThird"
        }
    }
}

的json，在hjson中可以写为

Root:{
    First: {
        A: 一 //单行注释
        B: Two Second  # 还是单行注释
    }
    /*
        多行
        注释
    */
    "The Second": {
        C:
        '''
        Three
        Third
        '''
    }
}

更全面的介绍请参照[这里](Hjson, a user interface for JSON)

另外，上述结构的树状结构为

额外语法

此外，tModLoader中的hjson还支持颜色与引用。

如果需要编写彩色文本，可以使用 [c/16位颜色代码:字符串] 的格式。例如，

普通文本[c/FF0000:红色文本]普通文本

这样的文本会显示为

普通文本红色文本普通文本

引用的语法为 {$路径} 。

例如，在上述例子中，{$Root.First.B} 相当于 Two Second 。

引用的效果可以随着自动改变。例如，如果一个名叫Mods.MyMod.Common.Key的项在en-US.hjson中为 English ，在zn-Hans.hjson中为中文，那么，当语言选择为中文时 {$Mods.MyMod.Common.Key} 将会显示为中文，而在选择英文时将会显示为English。

因此，为了减少自己与翻译者的重复操作，建议尽可能多地使用引用。

在Mod中使用语言文本

目录结构

在制作Mod时，语言文本需要放置在 Mod根目录\Localization 中，文件名为 语言代码.hjson 。

例如，名叫 MyMod 的Mod中，中文语言文件的路径为 MyMod\Localization\zh-Hans.hjson

文件结构

在hjson文件中，最外的两层结构是Mods与MODID (MODID换为自己的) 。

Mods: {
    MODID: {
        
    }
}

文本位置

在1.4.4 tml中，每个类的文本在 Mods.<Mod名>.<类型>.<类名>.<属性> 中。

其中， Mod名 为对应Mod的类名，类型为Items，Buffs等。

该类的每个 LocalizedText 成员的名称都可替换 “<属性>” 。

例如，ModItem 类内置了两个LocalizedText成员： DisplayName 与 Tooltip, 分别对应名称与工具提示。

因此，对于 MyMod 中一个类名为 TestSword 的物品，若希望使其名为 测试剑 ，工具提示为 村里最好的剑 ，就可写为

Mods: {
    MyMod: {
        Items: {
            TestSword: {
                DisplayName: 测试剑
                Tooltip: 村里最好的剑
            }
        }
    }
}

更进一步，属性也可以被自定义，只要在对应的类内使用 this.GetLocalization方法。

具体地说，使用this.GetLocalization(str)(str为一字符串)，将会返回对应类内的str的值对应的属性的文本(以LocalizedText类型)。

例如，若将上文中 TestSword 项改为

            TestSword: {
                DisplayName: 测试剑
                Tooltip: 村里最好的剑
                Broken: 这把剑断了
            }

，那么在 TestSword 类中使用this.GetLocalization("Broken") 将会返回值为 “这把剑断了” 的LocalizedText变量。

需要注意的是，只有实现了 ILocalizedModType 的类才可使用该方法。幸运的是，大部分常用的类都满足这一条件。

手动调用本地化文本

在制作mod时，有时需要调用类外的文本。这时，则需要使用 GetText 方法或GetTextValue方法。这两个方法均在 Terraria.Localization.Language 下。

对于字符串常量，只需将原始的字符串替换为 Language.GetTextValue(路径) 即可。

若需要获取 ModTranslation 类型(如修改内置属性)，则可使用Language.GetText(路径)。

路径的第一层为 Mods ，用 . 分割。

例如，若希望获取储存在 “Mods.MyMod.Common.MyString” 的文本，可以使用

Language.GetTextValue("Mods.MyMod.Common.MyString")

省略外层嵌套

在大部分情况下，hjson文件的最外两层都是Mods.<Mod类名>，为了简单起见（减少缩进），在hjson文件名后可以加上一个 _<名称> 和多个 .<键名> 来省略对应的层。

例如，仍使用上面的例子(不包括Broken属性)，令其原本写在 zh-Hans.hjson 中。

那么，可以将其移动到 zh-Hans_Mods.MyMod.hjson 中,并改为

Items: {
    TestSword: {
        DisplayName: 测试剑
        Tooltip: 村里最好的剑
    }
}

同样，可以将其移动到 zh-Hans_Mods.MyMod.Items.hjson 中，并改为

TestSword: {
    DisplayName: 测试剑
    Tooltip: 村里最好的剑
}

手动覆盖内置属性

在 SetDefault 被移除后，如物品的名称、物品的工具提示等内置属性一般通过hjson文件直接编辑。然而，如果需要在程序中修改这些属性，就需要使用 override。

例如，若有一个物品的 Tooltip 属性需要覆盖为在 Mods.MyMod.Common.MyString 下存储的字符串，那么，可以在该物品类中添加

public override LocalizedText Tooltip => Language.GetText("Mods.Mymod.Common.Mystring");

内置工具提示(还有向文本传值)

在实际的mod制作中，很多工具提示都有着很高的通用性。例如，若创造了一种恢复药水，那么一般情况下会添加类似 恢复123生命值 等内容。这种情况下，比起手动为每个语言添加翻译，更方便的方法是调用内置的文本。

具体来说，在 CommonItemTooltip. 内有许多原版terraria中的工具提示。

例如，在上面的例子中，可以使用 CommonItemTooltip.RestoresLife ，

其值为恢复{0}生命值。

值得注意的是，这里的回复量显示为 {0} ，因此，需要用具体的值替换这个占位符。

为了达成这个目标，可以使用 LocalizedText 类中的 WithFormatArgs 方法。

该方法可以传递多个对象，依次替换{0}，{1}，以此类推。

例如，在上述例子中，就可以使用

//使用base.XXX调用基类的对应函数
public override LocalizedText Tooltip => base.Tooltip.WithFormatArgs(123);

此外，在引用时可能会出现存在多个{0}的情况。为了解决这个问题，可以在引用时修改为 {原引用@偏移值}，这样可以将原引用的每个通配符的位置加上偏移值。

例如，{CommonItemTooltip.RestoresLife@1} 相当于恢复{1}生命值 ，

而 {CommonItemTooltip.RestoresLife@2} 相当于恢复{2}生命值 。

关于CommonItemTooltip的全表，请参照tml官方wiki。

让你的Mod变得”国际化”——1.4.4版

基础