Fu004/minecraft-vi-copywriting

Minecraft服务器的越南语文风

目标：玩家看到的每一个字都必须读起来像一位友善的管理员在说话——不像行政公文、不像谷歌翻译，也不粗俗无礼。游戏术语必须与Minecraft官方越南语版本一致，让玩家一眼认出。

在修改或编写以下内容时使用本技能：messages.yml、vi.yml、lang/*.yml、messages_vi.properties、物品配置文件的display-name/lore、GUI/菜单、全息投影、计分板、TAB、NPC对话、广播/公告、教程、title/actionbar。

编写新插件时也使用本技能（Java/Kotlin，Paper/Spigot/Velocity...）：代码中玩家看到的所有字符串和插件附带的默认语言文件必须从一开始就遵循本技能——参见第8节。

---

1. 处理流程

1. 修改前先阅读整个文件。 确定：
   • 颜色语法：传统 &a / §a、十六进制 &#RRGGBB，还是MiniMessage <green>、<gradient:...>。保持文件已有的语法，不要混用。
   • 占位符：%player%、{0}、{player}、<player>、%vault_eco_balance%... — 记录下来。
   • 当前使用的称呼和语气（通常是"bạn"）。如果文件已有自己一贯的语气，遵循该语气。
   • 如果项目有术语文件（如 docs/thuat-ngu.md、glossary.md），则阅读并遵守——它优先于任何其他来源。
2. 查询术语 针对文件中出现的方块/物品/生物/效果/附魔/属性名称（参见第2节）。
3. 逐行分类 根据第4节（错误、成功、信息、教程、NPC对话、公告、物品名称、lore、GUI按钮、title/actionbar）。
4. 重写 根据第3节 + 第4节。已合适的行则保留原样——不要为改而改。
5. 技术检查（第6节），验证文件。
6. 报告 根据第7节。

---

2. 参考来源——借用术语，不借用句子

现有的越南语本地化版本非常适合统一用词，但它们的句子通常直译自英文（"Số dư hợp lệ không đủ"、"Việc xử lí yêu cầu dịch chuyển đã bị hủy"）。因此：借用词语，不借用句子。

选词优先级顺序：

1. 项目的术语文件（如果有）。
2. Minecraft vanilla vi_vn — 方块、物品、生物、效果、附魔、属性、游戏模式、难度的标准来源。客户端设置为越南语的玩家会在游戏中看到这些词，因此lore/消息必须与之匹配。
   • 查询地址：https://raw.githubusercontent.com/InventivetalentDev/minecraft-assets/<版本>/assets/minecraft/lang/vi_vn.json（例如 <版本> = 1.21）。文件很大——通过key搜索（item.minecraft.diamond_sword、effect.minecraft.speed、enchantment.minecraft.sharpness、attribute.name.generic.attack_damage、gameMode.creative...），而不是通读。
   • 不确定时不要凭记忆猜测vanilla名称——查询文件，或在报告中标记“需要确认”。
3. EssentialsX messages_vi.properties — 参考常见插件概念的用词（传送、昵称、重生点、邮件...）：https://raw.githubusercontent.com/EssentialsX/Essentials/2.x/Essentials/src/main/resources/messages_vi.properties。
4. 越南玩家实际的说话方式（第3节）。

已校对术语

来自 vanilla vi_vn（1.21）— 在lore/属性中必须这样使用：

英文	vi_vn
Armor	Giáp
Armor Toughness	Độ bền áo giáp
Attack Damage	Sức tấn công
Attack Speed	Tốc độ tấn công
Max Health	Sinh lực tối đa
Movement Speed	Tốc độ
Knockback Resistance	Kháng đẩy lùi
Luck	Vận may
Mining Efficiency	Hiệu quả đào
Anvil	Cái đe
Ancient Debris	Mảnh vỡ cổ đại
Nether, The End	保留 "Nether"、"The End"

来自 EssentialsX vi（参考概念）：

概念	EssentialsX vi	聊天/GUI建议
teleport	Dịch chuyển	"dịch chuyển" 或 "tp"（快速聊天）
enchantment	Phù phép	Phù phép
inventory	Túi	Túi đồ
item	Vật phẩm	GUI/标题中用 "Vật phẩm"，聊天句子中用 "đồ"
nickname	Biệt danh	Biệt danh
spawn point / bed	Điểm hồi sinh	Điểm hồi sinh
gamemode	Chế độ chơi (Sinh tồn、Sáng tạo、Phiêu lưu)	保留原样
ender chest	Rương ender	Rương ender
kit	Bộ dụng cụ	"kit" — 与命令 /kit 名称一致，玩家习惯这么说
experience	Kinh nghiệm	Kinh nghiệm / EXP
offline	Ngoại tuyến	"offline"
server	Máy chủ	"server"

通用规则：游戏中存在的物体名称（方块、物品、生物、效果、附魔、属性）→ 遵循 vanilla vi_vn。玩家习惯用英文称呼的服务器/插件概念（kit、warp、home、rank、spawn、server、online/offline、AFK、PvP、top）→ 保留英文。 选定后，在整个服务器使用同一个词。

借用词语但重写句子——EssentialsX vi 示例

原始本地化版本	重写后
Bạn không có quyền để dùng lệnh này.	Bạn chưa có quyền dùng lệnh này.
Số dư hợp lệ không đủ.	Bạn không đủ tiền.
Bạn không thể thanh toán cho người chơi ngoại tuyến.	{0} đang offline, không chuyển tiền được.
Bạn không thể nhập lệnh đó trong {0}.	Đợi {0} nữa mới dùng lại được.
Dịch chuyển sẽ bắt đầu trong {0}. Đừng di chuyển.	Đứng yên {0}, sắp dịch chuyển...
Việc xử lí yêu cầu dịch chuyển đã bị hủy.	Đã hủy dịch chuyển vì bạn di chuyển.
Người chơi {0} chưa bao giờ vào máy chủ.	{0} chưa vào server lần nào.
Công cụ này còn {0} lần sử dụng nữa.	Công cụ này còn dùng được {0} lần.
Bạn không thể dùng bộ dụng cụ này trong {0}.	{0} nữa mới nhận lại kit này được.
Túi của bạn đã đầy.	Túi đồ đầy rồi, dọn bớt nhé.
Essentials đã được tải lại {0}.	Đã reload Essentials {0}.

重写插件的 messages_vi.properties 文件时，保留 .properties 的转义符（\:、\!、'' 配合 MessageFormat）。

---

3. 语气原则

自然、简洁、明确需要做什么。

• 默认称呼： 系统称呼玩家为 "bạn"，不自我称呼（或必要时用 "server"）。不要用 "Quý khách"、"Người chơi" 直接称呼。不要用 "mày/tao"，除非是NPC对话且有明确的个性。
• 先短后全。 删掉冗余短语："để có thể"、"thực hiện"、"tiến hành"、"việc..."、"đã được ... thành công"、"hiện tại"、"một cách"、"hợp lệ"。
• 主动代替被动： "đã bị hủy" → "đã hủy"；"đã được tải lại" → "đã reload"。
• 说明需要做什么，而不仅仅是报告错误。 "Sai cú pháp" → "Dùng: /pay <tên> <số tiền>"。如果有原因，说明原因。
• 优先使用越南语固有词 / 玩家常用词，而不是沉重的汉越词或机器翻译词："sử dụng" → "dùng"；"hoàn tất" → "xong"；"không hợp lệ" → "không đúng" / 直接说明什么是对的；"trực tuyến/ngoại tuyến" → "online/offline"；"máy chủ" → "server"。（例外：游戏内物品名称仍遵循 vanilla vi_vn — 第2节。）
• 语气助词（nhé、nha、đó、rồi、nè、thôi）： 用于软化句子，但每句最多一个语气助词，也不是每句都要有。严重警告/封禁/踢出时不要用语气助词。
• 感叹号节制： 最多一个 !，仅用于高兴的消息或事件。不要 !!!。
• 越南语大写规则： 仅句首字母和专有名词大写。物品名称/事件名称/GUI标题可以每个词首字母大写。避免全大写，除非是像 [VIP]、MỚI 这样的简短标签。
• 不粗俗： 不骂人、不讽刺玩家、不用网络火星文（"ko"、"dc"、"j"、"z"）、不用难懂的缩写。
• 一致性： 同一概念在整个服务器中使用同一个词（如果选了 "xu" 就不要混用 "coin"/"tiền"）。
• 单数/复数： 越南语不区分单复数——像 day/days 这样的key翻译相同（"ngày"）。

需要修改的“机器味”迹象

机器味	更自然
Vui lòng ...	（去掉，或改为邀请语气："... nhé"）
... đã được thực hiện thành công.	Đã ... / ... xong rồi.
Việc ... đã bị hủy.	Đã hủy ...（附带原因）
Đã xảy ra lỗi. Vui lòng thử lại sau.	Có lỗi rồi, thử lại sau chút nhé. Vẫn lỗi thì báo admin.
Người chơi được chỉ định không tồn tại.	Không tìm thấy người chơi %player%.
Lỗi: Đầu vào không hợp lệ. / Số không hợp lệ.	Nhập số thôi, ví dụ: 10
Cần phải là một số khác không.	Số lượng phải lớn hơn 0.
Thanh Kiếm Của Lửa	Kiếm Lửa / Hỏa Kiếm

---

4. 按文本类型

错误/拒绝 — 简洁、冷静、指出解决方法。红色/橙色。

• Bạn phải chờ %time% giây trước khi có thể sử dụng lại. → Từ từ đã, %time%s nữa mới dùng lại được.

成功 — 简短确认，附带具体结果。

• Giao dịch đã được hoàn tất thành công! → Đã chuyển %amount% xu cho %target%.

信息/状态 — 直接陈述信息。

• Người chơi %player% hiện tại không trực tuyến. → %player% đang offline.

教程/指导 — 分步骤，句首用动词，每行一个要点，给出具体命令。

• Để có thể mở khóa tính năng này, bạn cần phải đạt được cấp độ 10. → Lên cấp 10 để mở khóa.
• 多个步骤：1. Gõ /is create để tạo đảo / 2. Chặt cây, làm bàn chế tạo / 3. Gõ /is help nếu bí

NPC对话 — 根据角色有个性，使用合适的称呼（"ta – ngươi"、"tôi – cậu"、"chú – cháu"），但易懂且每句不超过2行聊天。每个角色保持语气一致。

• Xin chào người chơi. Tôi có một nhiệm vụ dành cho bạn. → Ê, cậu kia! Rảnh không? Tôi đang cần người giúp một chuyện.

公告/广播 — 开头有钩子，明确说什么——什么时候——在哪里——做什么。1–3行。

• Sự kiện Boss Thế Giới sẽ bắt đầu sau 5 phút. Hãy chuẩn bị. → 5 phút nữa Boss Thế Giới xuất hiện! Gõ /warp boss, rủ team đi cùng.

物品名称 — 1–4个字，有画面感，不要用 "Của"。稀有/传说物品可以使用汉越词（Hỏa Long Kiếm、Băng Tâm Giáp），但不要无意义拼凑。基础/变种 vanilla 物品则遵循 vanilla vi_vn 名称。每个词首字母大写。

Lore — 每行不超过约35个显示字符。建议顺序：

1. 1–2行风味文字（灰色、斜体）— 简短、有灵魂。
2. 空行。
3. 简洁属性，使用 vanilla 属性名称：+10% Sức tấn công、+2 Giáp、+15% Tốc độ。
4. 空行 + 使用方式：Chuột phải để dùng。
5. 最后是稀有度。

GUI按钮/菜单标题 — 1–3个字：Mua、Bán hết、Quay lại、Trang sau、Xác nhận。按钮的lore说明后果：Click để mua 1 cái / Shift-click: mua 64。

Title / subtitle / actionbar — 极其简短（title ≤约20字符，subtitle/actionbar ≤约40字符）。

任务进度 — 模板“Còn {n} ... cần ...”格式：Còn 5 khối cần phá、Còn 3 con cừu cần xén lông。

---

5. 不要过度

• 不要把每句话都变成玩笑或梗——服务器仍然需要清晰明了。
• 不要"幼稚化"（"bro"、"ngon lành cành đào"...），除非文件已经用了那种语气。
• 如果文件还未使用，不要添加emoji/特殊字符；如果使用，检查资源包字体是否能显示。
• 不要改变原意，不要删掉信息（数字、条件、命令）。
• 不要"本地化"命令名称、命令参数或实际的世界/warp名称。
• 小心对待玩家必须原样输入的字符串（例如BetonQuest的前缀 password:）：翻译为带声调的文字会要求玩家输入声调——标记出来让用户决定。

---

6. 技术检查（必做）

• 不修改key，只修改value。保留列表结构（如果lore是列表则仍然是列表）。
• 100%保留占位符和颜色/格式标签，包括像 @[legacy]、@[minimessage] 这样的前缀。可以调整占位符在句子中的位置，但不能更改名称或删除。
• 调整句子顺序时，将颜色标签重新放置在占位符之后（例如 &e%player% &7đã vào server；MiniMessage：<secondary>{0}<primary> ...）。
• YAML：以 &、%、{、<、[、*、!、@ 开头或包含 : / # 的字符串必须用引号括起来。在单引号内，' 写为 ''。
• .properties（EssentialsX、LuckPerms...）：保留 \:、\! 和 ''（当字符串使用 MessageFormat {0} 时）。
• 如果插件需要，保留 \n 和换行符与原始文件一致。
• 不要触碰配置行如 configVersion。
• 文件保存为 UTF-8 无 BOM，越南语带全声调，使用预组Unicode（NFC）。
• 修改后验证YAML：python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1],encoding='utf-8'))" <file>。
• 使用正则表达式 %[^%\s]+%|\{[^\}]+\}|<[^>]+>|&[0-9a-fk-or]|&#[0-9a-fA-F]{6}|@\[[a-z]+\] 逐一key对比新旧版本之间的key和占位符集。
• 如果发现原始文件中已有的错误（例如两个命令描述放反了），则修正为正确含义并在报告中明确指出。

---

7. 报告格式

已修改 messages.yml 中的 23/80 行（57行保留原样，因为已合适）。

| Key | 修改前 | 修改后 |
|---|---|---|
| economy.not-enough | Bạn không đủ số dư để thực hiện giao dịch này. | Bạn không đủ tiền (cần %price%). |

已查询 vanilla vi_vn 术语：<key> → "<từ>"

需要您确认：
- `quest.npc-3`：不清楚这个NPC是谁——目前保持中性语气。

---

8. 编写新插件时

新插件中的文本从一开始就正确编写，以后就不用逐行修改。对于玩家看到的所有字符串应用第2–6节，再加上以下规则。

将字符串与代码分离

• 不要在 sendMessage、Component.text、title、GUI、lore 等中硬编码玩家看到的字符串。 所有字符串通过语言文件（如 src/main/resources/lang/vi.yml）和key查找层（Messages.get("economy.not-enough", ...)）传递。
• 越南语是附带的语言文件的默认语言。 如果需要多语言，并行添加 en.yml，使用相同的key集。
• 默认语言文件在首次运行时复制到插件目录（saveResource），而当插件更新时，仅添加缺失的新key到管理员已修改的文件中，而不是覆盖他们已修改的文本。
• 将前缀（[MyraMC]）设为一个单独的key，通过占位符 <prefix> 插入——不要在每条消息中重复前缀。

设置key和占位符

• 按键能组分组，格式为 nhom.tinh-huong：economy.pay.success、economy.pay.not-enough、teleport.cancelled-moved、gui.shop.title。
• 占位符使用名称，不使用位置索引：<player>、<amount>（MiniMessage）或 {player} — 不要使用 {0}、{1}。越南语常常需要调整语序以符合习惯，有名称的占位符可以帮助翻译/修改者不出错。
• 不要在代码中通过拼接字符串来构造句子（"Bạn nhận " + amount + " " + item）。始终将完整句子放在语言文件中并包含占位符，因为不同语言的词序不同。
• 每个key是针对一种情况的完整句子。不要将一个句子片段在多个地方复用（例如不要定义一个单独的 "xu" 字符串然后在整个代码中 {coin_name}）。如果需要复用，使用 MiniMessage 标签 <item_display> 并在多个key中引用。
• 提示和视觉一致性： 错误消息使用 <red> 标签，成功消息使用 <green>，信息消息使用 <gray> 或 <white>。在语言文件的开头定义主色调和强调色为 MiniMessage 标签（例如 <primary><aqua>、<secondary><gray>），然后在消息中使用 <primary>、<secondary> 而不是直接使用颜色代码。

处理命名型和位置型占位符

如果使用 Paper API 且框架要求位置型占位符（{0}、{1} 配合 MessageFormat 或 Component.translatable），则：

• 为每个语言文件添加一个说明行，列出每个key中 {0}、{1} 的含义：# {0} = tên người chơi, {1} = số tiền
• 仍建议在下一个可用版本中切换到命名型占位符。
• 对于 MiniMessage 格式，始终使用 <tag> 形式。

---

9. 常见错误速查表

错误写法	正确写法	备注
Bạn đã nhận thành công huy chương.	Nhận huy chương rồi!	去掉“thành công”
Số điện thoại không hợp lệ.	Số điện thoại gồm 10 chữ số, ví dụ: 0912345678	告诉用户正确的格式
%player% đã vào server.	&e%player% &7đã vào server.	如果文件使用传统格式，需要带颜色标签
Bạn có muốn xóa đảo không? (Có/Không)	Xác nhận xóa đảo? Gõ /is confirm	避免交互式提示，改用命令确认
VIP	[VIP]	如果需要标签格式
Điểm hồi sinh của bạn đã được đặt lại	Đã hủy điểm hồi sinh. Gõ /spawn để về spawn.	不仅要报告发生了什么，还要告诉玩家下一步做什么