本地化¶

本地化（Localization）是指将Minecraft基岩版附加包中的用户可见文本翻译为多种语言的过程和机制。通过本地化系统，附加包可以自动根据玩家的语言设置显示对应语言的文本内容。

概述¶

基岩版使用语言文件（Language File）来存储本地化文本。语言文件以.lang为扩展名，存放在附加包的texts/目录中。每个语言文件对应一种语言或区域设置，文件名遵循语言代码格式，例如en_US.lang（美式英语）、zh_CN.lang（简体中文）、zh_TW.lang（繁体中文）等。

语言文件格式¶

语言文件是纯文本文件，每行定义一条翻译文本，格式如下：

翻译键=翻译值	##注释

翻译键（Translation Key）：一个唯一的字符串标识符，用于在游戏中引用该翻译文本。
翻译值（Translation Value）：实际显示给玩家的文本。
注释（Comment）：以两个井号##开头，可写在行首作为整行注释，也可写在翻译值之后作为行内注释。##之后直到行尾的内容都会被视为注释，不会在游戏中显示。

例如：

item.my_namespace:custom_sword.name=自定义宝剑	##这是一把自定义的剑
entity.my_namespace:custom_mob.name=自定义生物

空行和以##开头的行会被视为注释而忽略。

翻译键¶

附加包中的翻译键遵循以下命名约定：

对象类型	翻译键格式
物品名称	`item.<标识符>.name`
方块名称	`tile.<标识符>.name`
实体名称	`entity.<标识符>.name`
刷怪蛋名称	`item.spawn_egg.entity.<标识符>.name`
附加包名称	在清单文件中通过`name`字段引用
附加包描述	在清单文件中通过`description`字段引用

清单文件中的name和description字段也可以使用翻译键，游戏会自动查找对应语言文件中的翻译值来显示。

支持的语言¶

texts/目录下还应包含一个languages.json文件，用于声明附加包支持的语言列表。该文件为一个JSON字符串数组，例如：

["en_US", "zh_CN", "zh_TW", "ja_JP"]

基岩版目前原生支持以下29种语言：

文件ID	语言	国家/地区
`id_ID`	印度尼西亚语	印度尼西亚
`da_DK`	丹麦语	丹麦
`de_DE`	德语	德国
`en_GB`	英语	英国
`en_US`	英语	北美
`es_ES`	西班牙语	西班牙
`es_MX`	墨西哥西班牙语	墨西哥
`fr_CA`	加拿大法语	加拿大
`fr_FR`	法语	法国
`it_IT`	意大利语	意大利
`hu_HU`	匈牙利语	匈牙利
`nl_NL`	荷兰语	荷兰
`nb_NO`	书面挪威语	挪威
`pl_PL`	波兰语	波兰
`pt_BR`	巴西葡萄牙语	巴西
`pt_PT`	葡萄牙语	葡萄牙
`sk_SK`	斯洛伐克语	斯洛伐克
`fi_FI`	芬兰语	芬兰
`sv_SE`	瑞典语	瑞典
`tr_TR`	土耳其语	土耳其
`cs_CZ`	捷克语	捷克共和国
`el_GR`	希腊语	希腊
`bg_BG`	保加利亚语	保加利亚
`ru_RU`	俄语	俄罗斯
`uk_UA`	乌克兰语	乌克兰
`ja_JP`	日语	日本
`zh_CN`	简体中文	中国
`zh_TW`	繁体中文	台湾地区
`ko_KR`	韩语	韩国

自定义语言¶

通过全局资源包，可在游戏支持的语言列表中注册自定义语言。自定义语言需要在资源包的texts/目录中同时提供以下两个文件：

languages.json：在已有数组中追加自定义语言代码（如xx_XX）。
language_names.json：定义各语言代码在选项菜单中的显示名称。

language_names.json示例

[
  ["xx_XX", "新语言（自定义语言#1）"],
  ["yy_YY", "维基语（自定义语言#2）"]
]

应用全局资源包后，即可在游戏设置的"语言"选项中选择新语言。

禁用资源包前请先切换语言

使用自定义语言时，若直接禁用其所属资源包而不先切换至其他语言，可能导致游戏崩溃。

原始文本¶

原始文本（Raw Text）是基岩版中用于在命令、NBT和脚本API等场景中构造可翻译文本的JSON格式。原始文本支持插入翻译键，游戏会在显示时将其替换为对应语言的翻译值，还支持参数替换和文本样式设置。

原始文本的典型结构如下：

{"rawtext": [{"translate": "翻译键", "with": ["参数1", "参数2"]}]}

翻译值中的%s和%1、%2等占位符会被with数组中对应位置的文本替换。

语言继承¶

当游戏在当前语言的语言文件中找不到某个翻译键时，会回退到en_US.lang（美式英语）中查找。如果en_US.lang中也不存在该键，则直接显示翻译键本身。因此，en_US.lang通常作为附加包本地化的基准语言文件。