> For the complete documentation index, see [llms.txt](https://docs.rainmad.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rainmad.com/resources/blackmarkets-player-run-contraband-operation/translate-strings.md).

# Translate Strings

All player-facing text lives in JSON locale files under **`/locales`**. The script ships with `en.json`.

## Switch language

Set the locale in `cfg.lua`:

```lua
cfg.locale = 'en' -- loads /locales/en.json
```

The value must match a file name in `/locales` (without the `.json`).

## Add a new language

1. Copy `locales/en.json` to a new file, e.g. `locales/fr.json`.
2. Translate the **values** only — never change the keys.
3. Set `cfg.locale = 'fr'` and restart the resource.

```json
{
    "prompt": {
        "open_laptop": "Ouvrir l'ordinateur",
        "knock_door": "Frapper"
    },
    "notify": {
        "no_permission": "Vous n'avez pas la permission pour cette action."
    }
}
```

{% hint style="danger" %}
Only edit the text on the **right** of each `:`. Changing or removing a key (the left side) will break the string and may error in-game.
{% endhint %}

## Placeholders

Some strings contain placeholders that the script fills in at runtime. Keep them exactly as they are, in a spot that still reads naturally:

* `%s` — a string (a name, an amount, an item label).
* `%d` — a whole number.
* `%s%%` — a number followed by a literal percent sign.

The same rule applies wherever a string lives — for example `notify.van_seized` and `ui.orders.order_placed`:

```json
"van_seized": "Van seized. %d items destroyed.",
"order_placed": "Order placed — arriving in ~%s min."
```

## Where text is grouped

The locale file is organized by area so you can find strings quickly:

| Section             | Covers                                                                                                                                                |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`            | Interaction prompts ("Open Laptop", "Knock"…)                                                                                                         |
| `notify`            | Server notifications                                                                                                                                  |
| `progress`          | Progress-bar labels                                                                                                                                   |
| `command`           | Command help text                                                                                                                                     |
| `blip` / `dispatch` | Map blips and police dispatch messages                                                                                                                |
| `activity`          | Vault/sales activity descriptions                                                                                                                     |
| `editor`            | Placement-tool hints (drop / NPC vendor / warehouse editors)                                                                                          |
| `ui.*`              | Every NUI panel: laptop tabs, orders, stock, pricing, vault, analytics, members, inbox, settings, van, sale, customer, phone app, door, admin, editor |

{% hint style="info" %}
The `ui` section is by far the largest — it holds all the in-panel text. Translate it last, once the gameplay strings (`prompt`, `notify`) are done, so you can test in-game as you go.
{% endhint %}