This page is for someone who wants to translate an NPC they did not make. If you made the NPC and want to ship translations with it, see Translate your own NPC. How the translation files are written is on Localization.
How it works#
A translation pack is its own small mod: your translated text, your own manifest.json, and nothing from the NPC's mod. Players install it as a separate folder in Mods, next to the NPC's mod, and NPC Helper 2 applies it when the game starts.
Your pack needs:
- its own name,
UniqueID, author (you) and version; - a dependency on the NPC's mod, so SMAPI loads that mod first;
- only the files under
NPCs/<NPC name>/locale/<language>/.
Other packs that change an NPC from another mod are the outfit pack and the portrait pack. See Kinds of packs.
Quick start#
npchelper new translation "Rei Thai" --locale th --from "<the NPC mod's folder>" --for TamKungZ.Rei.NPC --author "YourName"
--localeis the language code (see Choosing the language folder).--fromis the folder of the NPC's mod. Its texts are copied in, so you only replace the values.--foris theUniqueIDof the NPC's mod, from itsmanifest.json.--authoris your name.
Translate the files in NPCs/<NPC name>/locale/<code>/, then check:
npchelper validate "Rei Thai" --base "<the NPC mod's folder>"
It should end with 0 error(s), 0 warning(s), and it lists what is still untranslated.
By hand#
Rei Thai/ your pack, with your own folder name
├── manifest.json
├── mod.toml
└── NPCs/
└── Rei/ the NPC's internal name
└── locale/
└── th/ the language code
├── Rei.toml
├── Dialogue.toml
└── Marriage.toml
Only the files you translate are needed. Start with Rei.toml and Dialogue.toml.
manifest.json#
{
"Name": "Dr. Rei - Thai",
"Author": "YourName",
"Version": "1.0.0",
"Description": "Thai translation of Dr. Rei. Requires NPC Helper 2.",
"UniqueID": "YourName.DrRei.Thai",
"MinimumApiVersion": "4.0.0",
"ContentPackFor": {
"UniqueID": "Framework.Mod.NpcHelper",
"MinimumVersion": "2.5.0"
},
"Dependencies": [
{ "UniqueID": "TamKungZ.Rei.NPC", "IsRequired": true }
]
}
| Setting | What to put |
|---|---|
Name, Author, Version |
Your pack's own. The author is you. |
UniqueID |
A new ID of yours, usually YourName.PackName. Not the NPC mod's ID. |
ContentPackFor |
Framework.Mod.NpcHelper, with the oldest NPC Helper 2 version your pack works with. |
Dependencies |
The UniqueID of the NPC's mod, with "IsRequired": true. |
UpdateKeys |
Optional. The page of your own pack, not the NPC mod's. |
mod.toml#
NPCs = []
Locales = ["th"]
Translates = ["Rei"]
NPCs = []says the pack adds no NPC.NPCs = ["NPCs/Rei/"]also names the NPC it translates.Localeslists your languages, andTranslateslists the NPCs. NPC Helper 2 reports a listed language with no files, or an NPC that is not loaded.- Leave
EmbedLocalesout. It is for an NPC mod that ships its own languages (see Translate your own NPC).
All three are optional. NPC Helper 2 only reads NPCs/<NPC name>/locale/<code>/ from each content pack, and never loads an NPC from a translation pack.
Common mistakes#
| Mistake | Why it matters | Instead |
|---|---|---|
Copying the NPC mod's manifest.json or mod.toml |
Mod managers take your pack for the NPC mod and may overwrite its files or updates. | Write your own manifest, as above. |
| Using the NPC mod's folder name and extracting over it | It replaces the NPC mod's manifest.json and mod.toml. |
Give your pack its own folder name. |
No Dependencies on the NPC mod |
SMAPI cannot load the NPC mod first or warn when it is missing. | Add the dependency. |
NPC files or EmbedLocales in the pack |
A translation pack never adds an NPC, and the files are someone else's work. | Include only locale/<code>/ files. |
Credit and permission#
Your translation is based on someone else's text. Check the NPC mod's page for its translation rules, or ask the author. Name the author and link the original mod in your description, and publish your pack on your own page. Do not upload the NPC mod.
The Legacy form#
A translation placed in the NPC mod's own folder (for example Mods/MyNpcMod/NPCs/Rei/locale/ru/), with no manifest.json or mod.toml of its own, is Legacy. NPC Helper 2 still loads it, but:
- a mod manager cannot update it, because it is not a mod;
- nothing records who made it or which version it is;
- an update of the NPC mod can overwrite or mix with the copied files.
NPC Helper 2 treats it as a language folder of the NPC mod. See Embedded or legacy. Prefer a translation pack for new translations.
Updating, removing and replacing#
- To update, replace the pack's folder or let your mod manager do it. To remove it, delete its folder. Install only one copy of a translation.
- If the NPC mod already has a folder for your language, yours replaces it. See A separate pack replaces an embedded one.
- When the NPC mod changes, NPC Helper 2 compares your translation with it at startup and warns about missing lines. See Translation checks.
Workflow#
- Create the pack with
npchelper new translation. - Translate
Rei.tomlandDialogue.toml, thenMarriage.toml,Events.tomlandFestivals.tomlif you want them. AddSchedule.tomlonly to replace the schedule. - Keep each key exactly as in the original, and leave internal names and game identifiers unchanged.
- Run
npchelper validateas above. - Start the game with that language and talk to the NPC. If a line is still in the original language, check the locale code, path, file name and key.