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 you can add your own translations

• how you can change existing translations

• how you can support multiple languages

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 hierarchies. This is easy to break!

You can validate your file on yamllint.com, or check How To Yaml for more information.

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.

Do not overwrite original .json files - ArchiveXL will handle the merging for you. Put your files in a custom path.

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.