Translation files: .json

How Cyberpunk localization works

Summary

Created: Oct 06 2025 by mana vortex Last documented update: Oct 06 2025 by mana vortex

This page explains how the game uses .json files, how they are used for localization, and how you can use localization files to add your own translations

Wait, this is not what I want!

• For a more detailed guide, check How to Translate a Mod

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.

A localizationPersistenceOnScreenEntry has four properties:

femaleVariant	Default text
maleVariant	Special text for masc variant (e.g. for gendered languages), you can leave this empty unless you need it
primaryKey	The numeric key the game uses to look up translation entries. If you add entries, set this to 0 and let ArchiveXL handle it.
secondaryKey	The textual key the game uses to look up translation entries. Must be unique.

Adding translations with ArchiveXL

To add your own translations, you need to create an .xl file in your project's resources folder. Open it with a text editor of your choice, and put the following:

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

Adding multiple entries

One line per entry:

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

Adding multiple languages

One block per language:

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 as folder names.