Fu004/minecraft-vi-copywriting

Style d'écriture vietnamien pour un serveur Minecraft

Objectif : tout texte que le joueur voit doit se lire comme un administrateur sympa qui parle — pas comme un document administratif, pas comme Google Traduction, et pas non plus grossier ou impoli. Les termes du jeu doivent correspondre à la version vietnamienne officielle de Minecraft pour que les joueurs les reconnaissent immédiatement.

Utilisez cette compétence pour modifier ou écrire : messages.yml, vi.yml, lang/*.yml, messages_vi.properties, fichier de config d'item (display-name, lore), GUI/menu, hologramme, scoreboard, tab, dialogue NPC, broadcast/annonce, tutoriel, title/actionbar.

À utiliser aussi lors de l'écriture d'un nouveau plugin (Java/Kotlin, Paper/Spigot/Velocity...) : toutes les chaînes que le joueur voit dans le code et dans le fichier de langue par défaut du plugin doivent suivre cette compétence dès le départ — voir section 8.

---

1. Procédure

1. Lisez tout le fichier avant de modifier. Identifiez :
   • La syntaxe de couleur : legacy &a / §a, hex &#RRGGBB, ou MiniMessage <green>, <gradient:...>. Gardez la syntaxe du fichier, ne mélangez pas.
   • Les placeholders : %player%, {0}, {player}, <player>, %vault_eco_balance%... — notez-les.
   • Le ton et l'interpellation utilisés (généralement « bạn »). Si le fichier a déjà un ton cohérent, suivez-le.
   • Si le projet a un fichier de termes (ex. docs/thuat-ngu.md, glossary.md), lisez-le et suivez-le — il prime sur toute autre source.
2. Cherchez les termes pour les noms de bloc/item/mob/effet/enchantement/statistiques apparaissant dans le fichier selon la section 2.
3. Classez chaque ligne selon la section 4 (erreur, succès, information, instruction, dialogue NPC, annonce, nom d'item, lore, bouton GUI, title/actionbar).
4. Réécrivez selon les sections 3 et 4. Les lignes déjà bonnes sont conservées — ne corrigez pas pour corriger.
5. Vérification technique (section 6), validez le fichier.
6. Rapport selon la section 7.

---

2. Sources de référence — prenez les TERMES, pas le STYLE

Les traductions vietnamiennes existantes sont excellentes pour harmoniser le vocabulaire, mais leurs phrases sont souvent trop littérales ("Solde valide insuffisant", "Le traitement de la demande de téléportation a été annulé"). Donc : empruntez les mots, pas les phrases.

Ordre de priorité pour choisir un mot :

1. Fichier de termes du projet (si existant).
2. Minecraft vanilla vi_vn — source officielle pour les noms de bloc, item, mob, effet, enchantement, statistiques, mode de jeu, difficulté. Les joueurs utilisant le client en vietnamien verront ces mots dans le jeu, donc le lore/les messages doivent correspondre.
   • Cherchez sur : https://raw.githubusercontent.com/InventivetalentDev/minecraft-assets/<version>/assets/minecraft/lang/vi_vn.json (ex. <version> = 1.21). Fichier volumineux — cherchez par clé (item.minecraft.diamond_sword, effect.minecraft.speed, enchantment.minecraft.sharpness, attribute.name.generic.attack_damage, gameMode.creative...) plutôt que de tout lire.
   • Ne devinez pas un nom vanilla si vous n'êtes pas sûr — cherchez dans le fichier, ou marquez comme « à confirmer » dans le rapport.
3. EssentialsX messages_vi.properties — référence pour les concepts de plugin courants (téléportation, surnom, point de réapparition, courrier...) : https://raw.githubusercontent.com/EssentialsX/Essentials/2.x/Essentials/src/main/resources/messages_vi.properties.
4. Comment les joueurs vietnamiens parlent vraiment (section 3).

Termes déjà vérifiés

Mots vanilla vi_vn (1.21) — à utiliser tels quels dans le lore/statistiques :

Anglais	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	conserver "Nether", "The End"

Mots EssentialsX vi (référence conceptuelle) :

Concept	EssentialsX vi	Suggestion pour chat/GUI
teleport	Dịch chuyển	"dịch chuyển" ou "tp" (chat rapide)
enchantment	Phù phép	Phù phép
inventory	Túi	Túi đồ
item	Vật phẩm	"Vật phẩm" dans GUI/titre, "đồ" dans chat
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)	garder tel quel
ender chest	Rương ender	Rương ender
kit	Bộ dụng cụ	"kit" — correspond à la commande /kit, les joueurs sont habitués
experience	Kinh nghiệm	Kinh nghiệm / EXP
offline	Ngoại tuyến	"offline"
server	Máy chủ	"server"

Règle générale : les noms d'objets dans le jeu (bloc, item, mob, effet, enchantement, statistiques) → suivre vanilla vi_vn. Les concepts serveur/plugin que les joueurs appellent en anglais (kit, warp, home, rank, spawn, server, online/offline, AFK, PvP, top) → garder l'anglais. Une fois choisi, utilisez un seul mot pour tout le serveur.

Emprunter des mots mais corriger les phrases — exemples d'EssentialsX vi

Traduction vietnamienne originale	Réécriture
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}.

Lors de la réécriture d'un fichier messages_vi.properties de plugin, conservez les échappements .properties (\:, \!, '' avec MessageFormat).

---

3. Principes de ton

Naturel, court, et indique clairement quoi faire.

• Interpellation par défaut : le système appelle le joueur « bạn », ne s'interpelle pas (ou utilise « server » si nécessaire). N'utilisez pas « Quý khách », « Người chơi » pour s'adresser directement. N'utilisez pas « mày/tao » sauf si c'est dans un dialogue NPC avec une personnalité claire.
• Court d'abord, complet ensuite. Supprimez les mots superflus : "để 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ệ".
• Préférez l'actif au passif : "đã bị hủy" → "đã hủy" ; "đã được tải lại" → "đã reload".
• Dites ce qu'il faut faire, pas seulement l'erreur. "Sai cú pháp" → "Dùng: /pay <tên> <số tiền>". Si possible, donnez la raison.
• Privilégiez les mots purement vietnamiens / que les joueurs utilisent souvent plutôt que des sinismes lourds ou des mots de traduction automatique : "sử dụng" → "dùng" ; "hoàn tất" → "xong" ; "không hợp lệ" → "không đúng" / dites directement ce qui est correct ; "trực tuyến/ngoại tuyến" → "online/offline" ; "máy chủ" → "server". (Exception : les noms d'objets dans le jeu suivent vanilla vi_vn — section 2.)
• Particules finales (nhé, nha, đó, rồi, nè, thôi) : utilisez-les pour adoucir la phrase, mais au maximum une particule par phrase et pas à toutes les phrases. Pour les avertissements graves / bans / kicks, pas de particule.
• Points d'exclamation avec modération : maximum un !, seulement pour les bonnes nouvelles ou événements. Pas de !!!.
• Casse à la vietnamienne : seule la première lettre de la phrase et les noms propres sont en majuscule. Les noms d'item/noms d'événement/titres de GUI peuvent être en majuscule initiale sur chaque mot. Évitez le ALL CAPS sauf pour de courtes étiquettes comme [VIP], MỚI.
• Pas de vulgarité : pas d'insultes, pas de moquerie des joueurs, pas de "teencode" ("ko", "dc", "j", "z"), pas d'abréviations obscures.
• Cohérence : un même concept utilise un seul mot pour tout le serveur (si vous avez choisi "xu", n'alternez pas avec "coin"/"tiền").
• Singulier/pluriel : le vietnamien ne distingue pas le nombre — les clés comme day/days se traduisent de la même façon ("ngày").

Signes de « style robotique » à corriger

Style robotique	Plus naturel
Vui lòng ...	(supprimez, ou transformez en invitation : "... nhé")
... đã được thực hiện thành công.	Đã ... / ... xong rồi.
Việc ... đã bị hủy.	Đã hủy ... (avec la raison)
Đã 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. Par type de texte

Erreur / refus — court, calme, indique comment corriger. Rouge/orange.

• "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."

Succès — confirmation concise, avec résultat concret.

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

Information / statut — dites l'information directement.

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

Instructions / tutoriel — pas à pas, verbe en début de phrase, une idée par ligne, donner la commande précise.

• "Để 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."
• Plusieurs étapes : "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í"

Dialogue NPC — personnalité selon le personnage, utilisez une interpellation adaptée au rôle ("ta – ngươi", "tôi – cậu", "chú – cháu"), mais facile à comprendre et ≤ 2 lignes de chat par phrase. Chaque personnage garde son ton tout au long.

• "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."

Annonce / broadcast — accroche au début, dites clairement quoi – quand – où – que faire. 1–3 lignes.

• "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."

Nom d'item — 1–4 mots, évocateur, pas de "Của". Les sinismes sont autorisés pour les objets rares/légendaires (Hỏa Long Kiếm, Băng Tâm Giáp) mais ne faites pas d'assemblage insensé. Les objets de base/vanilla suivent le nom vanilla vi_vn. Mettez la première lettre de chaque mot en majuscule.

Lore — chaque ligne ≤ ~35 caractères affichés. Ordre suggéré :

1. 1–2 lignes de flavor (gris, italique) — courtes, avec âme.
2. Ligne vide.
3. Statistiques concises, utilisez les noms vanilla : "+10% Sức tấn công", "+2 Giáp", "+15% Tốc độ".
4. Ligne vide + utilisation : "Chuột phải để dùng".
5. Rareté à la fin.

Bouton GUI / titre de menu — 1–3 mots : Mua, Bán hết, Quay lại, Trang sau, Xác nhận. Le lore du bouton indique la conséquence : Click để mua 1 cái / Shift-click: mua 64.

Title / subtitle / actionbar — extrêmement court (title ≤ ~20 caractères, subtitle/actionbar ≤ ~40).

Progression de quête — modèle "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. N'en faites pas trop

• Ne transformez pas chaque phrase en blague ou meme — le serveur doit rester clair.
• Ne rendez pas le style trop juvénile ("bro", "ngon lành cành đào"...) sauf si le fichier utilise déjà ce ton.
• N'ajoutez pas d'emojis/caractères spéciaux si le fichier n'en a pas ; si vous en ajoutez, vérifiez que le resource pack les affiche correctement.
• Ne changez pas le sens original, ne supprimez pas d'information (chiffres, conditions, commandes).
• Ne traduisez pas les noms de commandes, paramètres de commandes, ou noms de mondes/warp réels.
• Faites attention aux chaînes que le joueur doit retaper (ex. préfixe password: de BetonQuest) : les traduire en vietnamien accentué obligera les joueurs à taper les accents — signalez-le pour que l'utilisateur décide.

---

6. Vérification technique (obligatoire)

• Ne changez pas les clés, changez seulement les valeurs. Conservez la structure de liste (si le lore est une liste, il reste une liste).
• Conservez à 100% les placeholders et les balises de couleur/format, y compris les préfixes comme @[legacy], @[minimessage]. Vous pouvez déplacer les placeholders dans la phrase, mais ne changez pas leur nom et ne les supprimez pas.
• Si vous réordonnez la phrase, réajustez la couleur après le placeholder (ex. &e%player% &7đã vào server ; MiniMessage : <secondary>{0}<primary> ...).
• YAML : les chaînes commençant par &, %, {, <, [, *, !, @ ou contenant : / # doivent être entre guillemets. Dans les guillemets simples, écrivez ' comme ''.
• .properties (EssentialsX, LuckPerms...) : conservez \:, \!, et '' lorsque la chaîne utilise MessageFormat {0}.
• Conservez \n et les sauts de ligne comme dans l'original si le plugin le nécessite.
• Ne touchez pas aux lignes de configuration comme configVersion.
• Sauvegardez le fichier en UTF-8 sans BOM, vietnamien avec tous les accents, Unicode pré-composé (NFC).
• Validez le YAML après modification : python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1],encoding='utf-8'))" <fichier>.
• Comparez les clés et les placeholders par clé entre l'ancienne et la nouvelle version avec une regex %[^%\s]+%|\{[^}]+\}|<[^>]+>|&[0-9a-fk-or]|&#[0-9a-fA-F]{6}|@\[[a-z]+\].
• Si vous repérez une erreur dans l'original (ex. deux descriptions de commandes inversées), corrigez-la pour qu'elle ait le bon sens et mentionnez-la clairement dans le rapport.

---

7. Format du rapport

Đã sửa 23/80 dòng trong messages.yml (57 dòng giữ nguyên vì đã ổn).

| Key | Trước | Sau |
|---|---|---|
| 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%). |

Thuật ngữ đã tra vanilla vi_vn: <key> → "<từ>"

Cần bạn xác nhận :
- `quest.npc-3` : không rõ NPC này là ai — đang giữ giọng trung tính.

---

8. Lors de l'écriture d'un nouveau plugin

Si le texte du nouveau plugin est écrit correctement dès le départ, vous n'aurez pas à le corriger ligne par ligne plus tard. Appliquez les sections 2 à 6 pour toutes les chaînes vues par le joueur, plus les règles ci-dessous.

Séparez le texte du code

• Ne hardcodez pas les chaînes vues par le joueur dans sendMessage, Component.text, title, GUI, lore... Toutes les chaînes passent par un fichier de langue (ex. src/main/resources/lang/vi.yml) et une classe de recherche de clé (Messages.get("economy.not-enough", ...)).
• Le vietnamien est la langue par défaut du fichier de langue fourni. Si le multilingue est nécessaire, ajoutez en.yml en parallèle, avec le même ensemble de clés.
• Le fichier de langue par défaut est copié dans le dossier du plugin lors du premier démarrage (saveResource), et lors d'une mise à jour du plugin, ajoutez les nouvelles clés manquantes dans le fichier de l'administrateur sans écraser le texte qu'il a modifié.
• Gardez le préfixe ([MyraMC]) dans une clé séparée, inséré via le placeholder <prefix> — ne répétez pas le préfixe dans chaque message.

Définissez les clés et les placeholders

• Clés par groupe de fonctionnalités, format groupe.situation : economy.pay.success, economy.pay.not-enough, teleport.cancelled-moved, gui.shop.title.
• Placeholders nommés, n'utilisez pas de positions : <player>, <amount> (MiniMessage) ou {player} — n'utilisez pas {0}, {1}. Les phrases vietnamiennes nécessitent souvent un ordre différent de l'anglais, les placeholders nommés aident le traducteur/modificateur à ne pas se tromper.
• Ne construisez pas de phrases par concaténation dans le code ("Bạn nhận " + amount + " " + item). Placez toujours la phrase entière dans le fichier de langue avec les placeholders, car l'ordre des mots varie selon la langue.
• Chaque clé est une phrase complète pour une situation. Ne réutilisez pas un fragment de phrase ailleurs.

---

9. Pour le code interne (Java/Kotlin)

• Component.text : utilisez une clé de traduction avec MiniMessage plutôt que de créer des composants en dur. Exemple :

  // Au lieu de :
  player.sendMessage(Component.text("Bạn nhận được " + amount + " xu").color(NamedTextColor.GREEN));
  // Faites :
  player.sendMessage(MiniMessage.miniMessage().deserialize(Messages.get("economy.receive", Map.of("amount", amount))));
  

• ItemStack#displayName et lore : lisez-les depuis le fichier de langue. N'utilisez pas de noms d'item en dur.
• Pour les messages souvent répétés (ex. getBalance), créez des méthodes d'aide dans le code.
• Sécurité : utilisez MiniMessage avec un contexte désérialiseur (désactivez les balises dangereuses translate, keybind, etc.). N'utilisez pas LegacyComponentSerializer sur l'entrée utilisateur sans l'échapper.

---

Suite — ce document sert de référence complète pour toute communication textuelle avec le joueur sur un serveur Minecraft en vietnamien.