NPC Helper 2/Docs

Create an NPC

Make a translation pack

For a translator: release a translation of someone else's NPC as its own mod with its own manifest.json, so a mod manager can update it.

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.

We recommend that a translation is its own mod with its own manifest.json (a translation pack). A pack with a manifest can be updated by your mod manager and shows where the translation came from, who made it, and which version you have. NPC Helper loads it into the NPC for you; players do not copy anything into the NPC mod.

A translation pack includes only locale TOML files; they override the matching NPC's text and do not add another NPC. Use the NPCs/<NPC name>/locale/<language>/ path:

text
Translation Pack/
├── manifest.json
├── mod.toml                 optional: NPCs = [], Locales, Translates
└── NPCs/
    └── Rei/
        └── locale/
            └── th/
                ├── Rei.toml
                ├── Dialogue.toml
                └── Marriage.toml

The pack#

Keep manifest.json, mod.toml and NPCs/ together in the translation pack folder, as shown above, with ContentPackFor set to Framework.Mod.NpcHelper. Install it as a separate mod with your mod manager, which can then update it on its own. NPC Helper asks SMAPI for its content packs and checks only NPCs/<NPC name>/locale/<code>/ inside each; it does not scan the Mods folder, and it never loads NPC definitions from a translation pack. A translation mod that is not a content pack for NPC Helper is not found.

mod.toml takes optional settings that help NPC Helper report mistakes:

  • NPCs = [] states that the pack intentionally defines no NPCs.
  • Locales = ["th", "pt-BR"] lists the languages the pack provides. A listed language with no files is reported.
  • Translates = ["Rei"] lists the NPCs the pack translates. If none of them is loaded, NPC Helper says so at startup and suggests the NPC you probably meant.
  • EmbedLocales is for an NPC pack that has its own language folders. See Translate your own NPC.

npchelper new translation writes both lists for you.

What happens when the NPC mod also has your language#

If the NPC mod already ships a folder for the same language, yours replaces it for that language. See A separate pack replaces an embedded one.

The Legacy form#

A translation that is copied into the NPC mod's own folder (for example Mods/MyNpcMod/NPCs/Rei/locale/ru/) and has no manifest.json of its own is Legacy. NPC Helper 2 still loads it, but we do not recommend it:

  • Your mod manager cannot update it, because it is not a mod.
  • Nothing records who made it or which version it is, so its source is hard to trace.
  • It falls behind when the NPC mod is updated, and updating the NPC mod can overwrite or mix with the copied files.

Files placed this way end up in the NPC mod's own folder, so NPC Helper 2 sees them as a language folder of the NPC mod, not as a separate mod. See Embedded or legacy for how they are labelled.

Make new translations as translation packs, as shown above. npchelper new translation creates the correct form. A manifest-only pack with NPCs = [] that carries no translation files is reported as a pack that does nothing.

Updating and removing#

To update a translation, replace its folder with the new version, or let your mod manager update it. To remove it, delete its folder from Mods. Players should install only one copy of a translation.

When the NPC mod changes, check your translation again: the game compares it with the NPC at startup and warns about missing lines. See Translation checks.

A simple workflow#

  1. Start from npchelper new translation, or copy the NPC folder's structure under locale/<language-code>/.
  2. Start with Rei.toml and Dialogue.toml; add only the lines you actually translate.
  3. Keep each translated key exactly aligned with the original key, and leave internal names and game identifiers unchanged.
  4. Add Marriage.toml only if you are translating marriage text. Add Schedule.toml only if you intend to replace the schedule.
  5. Launch the game with that language selected and check the NPC in-game. If a line is still in the original language, check the locale code, file path, filename, and key.
All versions