> For the complete documentation index, see [llms.txt](https://wiki.redmodding.org/cyberpunk-2077-modding/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/files-and-what-they-do/file-formats/translation-files--json.md).

# Translation files: .json

How Cyberpunk localization works

## Summary

**Created:** Oct 06, 2025 by [mana vortex](mailto:undefined)\
**Last documented edit:** 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](https://wiki.redmodding.org/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="https://1427525421-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4gzcGtLrr90pVjAWVdTc%2Fuploads%2Fgit-blob-439e1432fdd2fef9ce5a565f373ea2b8463ae980%2Fjson_default_translation.png?alt=media" 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
```

{% hint style="warning" %}
`.yaml` files use **indentation** (the number of spaces at the beginning of a line) to organize entries in hierarchies. This is easy to break!

You can validate your file on [yamllint.com](https://www.yamllint.com/), or check [How To Yaml](https://wiki.redmodding.org/cyberpunk-2077-modding/for-mod-creators-theory/core-mods-explained/tweakxl/tweakxl-changing-game-records/how-to-yaml-tweak-modding-basics.md#indentation) for more information.
{% endhint %}

#### Overwriting existing entries

You can overwrite entries that belong to the vanilla game or entries that have been added by other mods. Depending on what you want to overwrite, you'll need to specify the primary or secondary key in your entry.

* Game entries: Specify the **primary** key
* Entries from mods: Specify the **secondary** key

{% 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
