# Translation files: .json

## Summary

**Created:** Oct 06 2025 by [mana vortex](mailto:undefined)\
**Last documented update:** Oct 06 2025 by [mana vortex](mailto:undefined)

This page explains

* how the game uses .json files
* how you can [add your own translations](#adding-translations-with-archivexl)
* how you can [change existing translations](#overwriting-existing-entries)
* how you can support [multiple languages](#adding-multiple-languages)

{% hint style="info" icon="question" %}

#### Wait, this is not what I want!

* For a more detailed guide, check [How to Translate a Mod](/cyberpunk-2077-modding/modding-guides/everything-else/how-to-translate-a-mod.md)
  {% endhint %}

## What's a JSON file, precious?

This file type is where CDPR keep their lookup tables. Basically, any entries that need to be looked up at runtime get chucked into a json file and kept around for later.

## JSON for translations

You can find the translation entries under the following paths:

```
base/localization/<language>/
ep1/localization/<language>/
```

The default example to look at is `base\localization\en-us\onscreens\onscreens.json`.

<figure><img src="/files/wRzS3i34muWGey1HRIdN" alt=""><figcaption></figcaption></figure>

A `localizationPersistenceOnScreenEntry` has four properties:

<table><thead><tr><th width="205.3333740234375"></th><th></th></tr></thead><tbody><tr><td>femaleVariant</td><td>Default text</td></tr><tr><td>maleVariant</td><td>Special text for masc variant (e.g. for gendered languages), you can leave this empty unless you need it</td></tr><tr><td>primaryKey</td><td>The numeric key the game uses to look up translation entries. If you add entries, set this to 0 and let ArchiveXL handle it.</td></tr><tr><td>secondaryKey</td><td>The textual key the game uses to look up translation entries. Must be unique.</td></tr></tbody></table>

### Adding translations with ArchiveXL

To add your own translations, you need to create an [.xl file](https://wiki.redmodding.org/wolvenkit/wolvenkit-app/menu#new-file) in your project's [resources](https://wiki.redmodding.org/wolvenkit/wolvenkit-app/editor/project-explorer#resources) folder. Open it with a text editor of your choice, and put the following:

```yaml
localization:  
  onscreens:  
    en-us: 
      - path\to\your\file\with\translation_strings.json
```

`.yaml` files use **indentation** (the number of spaces at the beginning of a line) to organize entries in groups. This is easy to break!

If you run into problems, you can check your file on [yamllint.com](https://www.yamllint.com/).\
If that doesn't help, see if `red4ext/plugins/TweakXL/TweakXL.log` has any hits for your mod.

#### Overwriting existing entries

Make sure that the **secondary key** of your translation entry is identical with the one from the entry you want to replace.

{% hint style="info" %}
Do not overwrite original .json files - ArchiveXL will handle the merging for you. Put your files in a custom path.
{% endhint %}

#### Adding multiple entries

One line per entry:

```yaml
localization:  
  onscreens:  
    en-us: 
      - file1
      - file2
```

#### Adding multiple languages

One block per language:

```yaml
localization:  
  onscreens:  
    en-us: 
      - path\to\your\file\with\en-en\translation_strings.json
    jp-jp:
      - path\to\your\file\with\jp-jp\translation_strings.json
```

You can see the available languages in the [game files](#json-for-translations) as folder names.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/translation-files--json.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.