Translations

Lives in: game.json → locale / i18n · overlay files · optional story/strings.json

VN-Mikro ships one base language as the unsuffixed files, then optional locale overlays and an optional strings catalog for keyed text.

Most stories

1. Set "locale" in game.json to the language of your base files (the ones without a suffix).
2. List switcher locales under i18n.locales if settings should offer a language row.
3. Add script_en.txt (or whatever locale id) when you translate the story; keep the same moment ids.
4. Use text_key / label_key / display_name_key only when you want a shared catalog; literals still work without one.

Where this lives

{
  "locale": "uk",
  "title": "Мій візуальний роман",
  "title_key": "game.title",
  "i18n": {
    "locales": [
      { "id": "uk", "label": "UK", "label_key": "screen.settings.locale_uk" },
      { "id": "en", "label": "EN", "label_key": "screen.settings.locale_en" }
    ]
  }
}

project/
  game.json
  game_en.json
  themes/default.json
  themes/default_en.json
  screens.json
  screens_en.json
  story/
    script.txt
    script_en.txt
    strings.json
    strings_en.json
  characters/hana/default.json
  characters/hana/default_en.json

{
  "game.title": "Мій візуальний роман",
  "screen.settings.locale_uk": "Українська",
  "choice.help": "Допомогти Хані"
}

{
  "settings": {
    "content": {
      "blocks": [
        {
          "bind": "locale",
          "label": "Language",
          "label_key": "screen.settings.language",
          "style": "locale_button",
          "active_style": "locale_button_active"
        },
        {
          "type": "button",
          "label": "Back",
          "label_key": "screen.settings.back"
        }
      ]
    }
  }
}

Catalog shape: Strings catalog. Map: game.json.

Effective locale

1. Player / settings override (set_locale), if any.
2. Else game.json → locale.

That value picks which overlay files load. An overlay may contain a "locale" field, but it does not re-choose which files were loaded in that pass.

File naming

The locale id is inserted before the extension: foo.json → foo_uk.json, script.txt → script_uk.txt.

Missing overlay → keep the base file. No crash.

Merge rules

Strings catalog

Optional. Used when fields carry *_key.

Missing key → use the literal field (or the surface’s default). Games can ship with no catalog at all.

Key fields vs literals

Prefer key-only: set the *_key and put the copy in story/strings.json. Omit the sibling literal so the catalog is the single source. Keep a literal only as a standalone fallback when the key is missing.

Usual order: non-empty key and found in catalog → catalog value; else literal; else surface default.

check reports a keyed field that has no literal and no entry in the base catalog (i18n.missing_key).

Special cases:

• Button label: "" stays blank even if label_key is set (icon-only).
• Labelplate prefers a non-empty literal text / prefix / suffix before keys.
• Character display name: catalog → display_name → capitalized folder name.

Settings locale switcher

A settings { "bind": "locale" } block expands into the locales in i18n.locales as chips. The active one uses active_style (default locale_button_active) and is not clickable. Locales not listed in i18n.locales are rejected by set_locale.

Mid-session language switch

When the player picks another locale:

1. Config and theme reload for the new overlays.
2. Story reloads (script_<locale> / story_<locale> + strings).
3. Play restores the same node id and flags without replaying commands.
4. If that node id is missing in the new story, the previous locale is restored and a locale_unavailable notification shows.
5. On success: backlog relocalizes and open screens rebuild.

Keep node ids aligned across locale scripts if players can switch mid-game.

Usually you need

Related

Strings catalog · Title, pause and settings screens · Theme and the dialogue box · Pictures, sound, and folders