NPC Helper 2/Docs

Create an NPC

Translate your own NPC

For the author of an NPC mod: ship translation files inside your own NPC pack, mark them with EmbedLocales, and know what happens when someone else translates your NPC.

This page is for the author of an NPC mod who wants to ship translations together with the NPC. If you are translating someone else's NPC, make a translation pack instead. How the translation files themselves are written is on Localization.

Put the language folder in your NPC's folder#

A translation you ship yourself lives inside the NPC mod's own pack. NPC Helper 2 calls it an embed translation:

text
Mods/MyNpcMod/
├── manifest.json
├── mod.toml
└── NPCs/
    └── Rei/
        ├── Rei.toml
        ├── Dialogue.toml
        └── locale/
            └── es-ES/
                ├── Rei.toml
                └── Dialogue.toml

It is part of your mod, so it is updated together with the NPC, and it needs no manifest.json of its own.

Tell NPC Helper which languages you ship#

List them in mod.toml, so the log can tell your translations from files other people copied in by hand:

toml
EmbedLocales = ["es-ES"]

See EmbedLocales. A pack that sets it should require NPC Helper 2.4.1 or later.

If someone else translates your NPC#

A separate pack replaces an embedded one#

When a separate content pack has a folder for the same NPC with the same language folder name, and the folder holds at least one .toml file, that folder replaces the embedded folder of that name. The two are not merged line by line.

Example: the NPC mod ships locale/th/ with 100 lines, and a Thai translation mod covers 90 of them.

text
NPC mod                          Thai translation mod
NPCs/Rei/locale/th/    (100)     NPCs/Rei/locale/th/    (90)

With both installed and the game in Thai, the 90 lines come from the translation mod and the other 10 show in the NPC's original language. They do not fall back to the embedded Thai lines.

This is deliberate. Two translators rarely agree on how to address the player, how to write a place name, or how formal to be. Mixing their lines inside one conversation reads as one character who changes voice from sentence to sentence. A replacement keeps one translator's voice, and the missing lines are visible (and reported, see Translation checks at startup) instead of being hidden by another translator's text.

Things to know:

  • Only that language is replaced. If the NPC mod also ships es-ES, it stays as it is.
  • The folder name must match. A separate pack with locale/es/ does not replace an embedded locale/es-ES/. For the game language es-ES, es is read first and the embedded es-ES is applied over it, as described in Choosing the language folder. Folder names are matched without regard to upper and lower case.
  • An empty folder replaces nothing. The separate pack's folder needs at least one .toml file.
  • The startup log tells you. For example: The embedded 'th' translation of NPC 'Rei' is replaced by mod 'Rei-Thai-Translation'.
  • Two separate packs for one language do not replace each other. Both are applied in path order and the later one wins for a key they share. Avoid installing two translations of the same language for the same NPC.

Embedded or legacy#

Translations were not always released as content packs. Some were, and still are, downloaded as loose files that you extract into the NPC mod's own folder (for example Mods/MyNpcMod/NPCs/Rei/locale/ru/Dialogue.toml). NPC Helper 2 loads those files exactly like an embedded folder, because they are in the same place. It cannot see where the files came from. But for the checks below it helps to tell a folder the NPC's author ships from a folder somebody copied in later, because the second kind is the one that falls behind when the NPC mod is updated.

So every language folder inside the NPC mod's own pack is labelled either embed or legacy:

  • EmbedLocales in mod.toml is the reliable way. The author lists the languages the mod ships (EmbedLocales = ["es-ES"]). Every other language folder inside the pack is legacy. A regional folder follows its language, so listing th covers th-TH. See EmbedLocales.
  • Without EmbedLocales, NPC Helper 2 guesses. A folder is taken for legacy when its keys do not match the NPC (some lines missing, or lines the NPC does not have) and its files are older than the NPC mod's files. The reasoning: an author writes the embedded translation together with the NPC, so it matches in full; a hand-copied file comes from an older download and lags behind.

The guess uses file dates, which are only a hint. Extracting an archive, a git checkout, or copying files can change every date to the same moment. And a translation that the author shipped but forgot to update looks exactly like a hand-copied one. If the label matters to you, set EmbedLocales.

The label changes three things, and nothing about how the text is loaded:

  • The startup log shows (legacy) instead of (embed) for the language.
  • A warning about a legacy folder says it was copied by hand, for example copied by hand into mod 'MyNpcMod' (legacy).
  • When a separate pack replaces a legacy folder, the log says legacy instead of embedded.

A translation from a separate content pack is never legacy, however old it is. It can only be reported as incomplete or outdated.

If the log reports a problem#

  • If the log calls one of your own folders legacy, add EmbedLocales.
  • If it reports your embedded translation as outdated, update it or remove the folder. The checks are explained in Translation checks.
All versions