Localization

An NPC pack is the original version of the character. A locale folder is a small set of overrides for one game language. You do not need to copy every original file: add only the values you want to translate.

Start with one translated name#

If the NPC is called Rei, add a locale/th/Rei.toml file beside the original Rei.toml:

NPCs/Rei/
├── Rei.toml
└── locale/
    └── th/
        └── Rei.toml

Put this in the locale file:

DisplayName = "เรย์"

That is a complete translation file. Keep the internal NPC name (Name = "Rei") unchanged; translate DisplayName, which is what players see. A locale file does not create another NPC.

Choosing the language folder#

The folder name is a language code, not a translated language name:

locale/th/       Thai
locale/es-ES/    Spanish (Spain)
locale/pt-BR/    Portuguese (Brazil)

NPC Helper checks the most specific code first, then its language-only code. For example, for es-ES it checks locale/es-ES/ and then locale/es/. It uses the first folder that exists; it does not combine both folders. If that folder has no translation for a particular key, the original value remains.

English does not use a locale overlay. Folder matching is case-insensitive.

Which files go where?#

The locale folder mirrors the NPC's original files. Use the same filenames:

For example:

NPCs/Rei/
├── Rei.toml
├── Dialogue.toml
├── Schedule.toml
├── Marriage.toml
└── locale/
    └── th/
        ├── Rei.toml
        ├── Dialogue.toml
        └── Marriage.toml

There is deliberately no Schedule.toml in this example: the original schedule is already suitable for Thai, so it does not need an override.

Translating dialogue#

Create locale/th/Dialogue.toml. Use the same keys as the original [Dialogue] table, and include only the lines you are translating:

[Dialogue]
Introduction = "ไง... ฉันชื่อเรย์ เป็นผู้ช่วยหมออยู่ที่คลินิก ถ้าจะมาตรวจร่างกายก็ไม่ต้องเกร็งหรอกน่า || แต่ถ้าฉุกเฉิน ก็รีบพุ่งไปห้องฉุกเฉินนู่น... ให้ไวเลยนะ"
Mon2 = "เจอกันอีกแล้วนะ วันนี้พยายามอย่าหาเรื่องเจ็บตัวกลับมาล่ะ"
Rainy = "ฝนตกทีไรกลิ่นทุกอย่างดูสะอาดขึ้น... แต่บางทีก็เหม็นกว่าเดิม พกร่มมาด้วยล่ะ"

The keys above are examples from the Dr. Rei Thai translation. Introduction, Mon2, and Rainy are keys, not labels to translate. The text to the right of = is the part players read. Any original dialogue key you leave out continues to use the original line.

Keep the game's dialogue tokens when translating a line. For example, @ is replaced with the player's name, $h is a dialogue mood token, and || separates alternative text. Do not remove or translate a token unless you intend to change its behavior.

Translating the NPC file and gift tastes#

You can change a display name without copying the rest of Rei.toml:

DisplayName = "เรย์"

You can also override a complete gift-taste category. A category you include replaces that whole category; its list is not appended to the original list:

[GiftTastes]
Love = ["Diamond", "Coffee", "Starfruit", "Peach"]

This example replaces Rei's entire Love list. If you only want to translate dialogue and the displayed name, leave [GiftTastes] out. Keep item names and other game data valid for the game; do not translate internal identifiers just because they appear in a TOML file.

Schedules: the important exception#

Most translated values override matching keys and leave all other original values alone. Schedules do not work that way. If a locale Schedule.toml contains at least one valid entry in [Schedule], that localized schedule replaces the original schedule. It does not add a Monday route to the original week's routes.

[Schedule]
Mon = [
  "600 Hospital 1 18 1",
  "1100 Hospital 9 9 2",
]

This is a complete schedule override containing only the Monday route shown. Do not use a partial example like this if the NPC also needs their original Tuesday-to-Sunday routes: copy and provide all routes you want the NPC to keep. An empty [Schedule] table, or one without valid entries, does not replace the original schedule.

Usually, dialogue is what needs translation; leave Schedule.toml out of the locale folder unless the schedule itself should differ by language. The married schedule follows the same replacement rule and is the [Marriage] table in Schedule.toml.

Translating engagement, spouse dialogue, and vows#

These are all in locale/th/Marriage.toml, but each kind of text has its own table:

[Engagement]
AcceptMermaidPendant = "นี่มัน... จี้นางเงือกใช่ไหม? @... เธอกำลังขอฉันแต่งงานเหรอ? ฉัน... ตอบตกลง"

[Dialogue]
Rei0 = "ฉันยังไม่ชินเลยว่าเราหมั้นกันแล้ว ฉันยังนึกถึงตอนนั้นซ้ำๆ อยู่เลย.$l"
Good_0 = "ชีวิตกับเธอยังเหมือนฝันอยู่เลย... ในทางที่ดีนะ.$l"

[Wedding]
Vows = [
  "หึ... ไม่นึกเลยว่าวันนี้จะเป็นฉันเองที่ต้องจับชีพจรตัวเอง มันเต้นแรงชะมัด$h",
  "ฉันเย็บแผลให้คนมานับไม่ถ้วน สั่งให้ทุกคนหายใจลึกๆ... แต่ไม่เคยบอกใครเลยว่า ฉันเป็นของเธอแล้วนะ @$l",
  "คำสัญญาของฉันง่ายๆ เธอล้มเมื่อไหร่ฉันจะรักษา ทำงานหนักเกินไปฉันจะดุ แล้วฉันก็จะอยู่ข้างๆ เธอตลอด... นี่แหละใบสั่งยาของฉัน$l",
]

[Engagement] and [Dialogue] override matching lines; spouse dialogue you do not include remains unchanged. A non-empty valid [Wedding] Vows list replaces the original vows as a list. For the married daily route, use [Marriage] in Schedule.toml instead; [Marriage] is not the schedule table to use in Marriage.toml.

Distributing a translation separately#

A translation can be released independently from the NPC pack. Include only locale TOML files; they override the matching NPC's text and do not add another NPC. Use the same NPCs/<NPC name>/locale/<language>/ path in either distribution:

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

Mod-manager archive#

Keep manifest.json and NPCs/ together in the translation pack folder, as shown above. Install it as a separate mod with your mod manager. NPC Helper checks the standard locale path inside manifested mods and reads its locale files without loading NPC definitions from the translation pack. A mod.toml containing NPCs = [] makes clear that the pack intentionally defines no NPCs.

You can also install this archive manually by extracting it into Mods. Mod managers can install or rearrange files in different ways, so the Manual archive may not work with every mod manager. The translation is detected when the installed pack preserves the expected NPCs/<NPC name>/locale/<language>/ path.

Manual archive#

For a manual archive, place the locale files at the matching path inside the target NPC mod's folder, and put the translation manifest in its own folder:

Mods/
├── [HP] ReiMod/             existing NPC mod
│   └── NPCs/
│       └── Rei/
│           └── locale/
│               └── th/
│                   ├── Rei.toml
│                   ├── Dialogue.toml
│                   └── Marriage.toml
└── Dr. Rei Thai Translate/
    └── manifest.json

Extract the archive into Mods; its paths put the translation files in the right folders. Use the actual installed folder name of the NPC mod. Install either the Manual or the mod-manager archive, not both.

To update, install the new archive using the same method. If an update removes a locale file, delete the old file yourself because extracting an archive does not remove files that are no longer included. To uninstall a Manual translation, remove its manifest folder and its locale folder, taking care not to remove the NPC mod's other files. A mod-manager install can be removed through the manager.

A simple workflow#

1. 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.

Common questions#

Do I need to copy every original dialogue line? No. Untranslated keys use the original text.

Does locale/es-ES/ combine with locale/es/? No. The first matching folder is used. Put the complete set of regional overrides together in es-ES/, or use just es/ for all Spanish variants.

Will changing DisplayName rename the NPC internally? No. Keep Name and the NPC folder name unchanged; translate DisplayName.

Can I translate images here? No. Sprites and portraits are not localized.

Why did my original schedule disappear? A valid localized schedule replaces it. Copy every route you intend to retain, or remove the locale Schedule.toml file.

What if two translation packs change the same line? The NPC's own locale files are applied first, followed by separate matching locale packs. If several packs override the same key, one wins based on the packs' path order. Avoid installing multiple translations for the same NPC and language.