> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: Localization
description: Translate your extension's menu text with langs/*.json files or ui.Localize.
icon: languages
sidebar_position: 2
---

# Localization

An extension can show its menu text in the language that the user selected.
Put one JSON file per language in a `langs` folder. Neverlose loads these files
for you, so you do not need to read them from Lua.

## Folder layout

<Tree.Folder name="MyExtension" icon="folder" defaultOpen>
  <Tree.File name="extension.json" icon="file-cog" />

  <Tree.File name="main.lua" icon="file-braces-corner" />

  <Tree.Folder name="langs" icon="folder" defaultOpen>
    <Tree.File name="ru.json" icon="file-json" />
  </Tree.Folder>
</Tree.Folder>

The file name is the short name of the language, such as `ru.json` for
Russian. You do not need to list the files in `extension.json`.

## Write the menu in English

Create the menu with readable English text. This text is the key that the
translation files use.

```lua main.lua
local tab = ui.AddTab("My extension")
local group = tab:AddGroup("General")
local enabled = group:AddToggle("Enabled", false)

enabled.tooltip = "Enable the feature"
```

## Add a translation file

Each file is a flat JSON object. A key is the English text from your script,
and the value is the translation.

```json langs/ru.json
{
  "My extension": "Моё расширение",
  "General": "Основное",
  "Enabled": "Включено",
  "Enable the feature": "Включить функцию"
}
```

<Note>
  **No `"strings"` wrapper.** The files that translate the main Neverlose menu
  put their text inside a `"strings"` object. Extension files do not.
</Note>

## How text is chosen

<Steps>
  <Step title="Files load before main.lua" icon="file-down">
    Neverlose reads `langs/*.json` before it runs your script. When the user
    changes the language, the menu switches to the matching text.
  </Step>

  <Step title="Lookup falls back" icon="list-ordered">
    Neverlose looks for the selected language first, then its base language,
    then English.
  </Step>

  <Step title="Your files override your requirements" icon="layers">
    Translations from your [requirements](/cs2/api_reference/extensions/requirements)
    load first, and your own files load last. If both have the same key, your
    translation wins.
  </Step>
</Steps>

Each extension has its own translations. The same text used in two places of
one extension shares one translation.

## Add translations from Lua

[`ui.Localize`](/cs2/api_reference/rendering/ui) adds one translation while
the script runs:

```lua
ui.Localize("ru", "Enabled", "Включено")
```

It keeps the translation in memory only and does not write a JSON file. It
throws `invalid language` if Neverlose does not know the language.

## Rules

<Card title="Keys and values" icon="list-check">
  * **Use readable English text as keys.** Do not use IDs such as
    `"feature_enabled"` with an `en.json` file. Creating tabs, groups, tooltips,
    and some other elements sets the English text back to the key itself.
  * **Change the translation, not the key.** The original text also identifies
    the element and its saved setting. Renaming it in Lua breaks both the
    translations and the user's saved value.
  * **Values must be strings.** A key whose value is not a string is skipped
    with an error in the console.
  * **Keep keys at 1000 bytes or less.** A longer key is skipped with an error.
    A longer translation is cut to 1000 bytes without splitting a UTF-8
    character.
  * **Keep the file valid JSON.** An invalid file is skipped with the error
    `invalid langs/<language>.json`.
</Card>

<Warning>
  **A file does not add a new language.** Neverlose only looks for files named
  after languages that it already knows. `ru.json` works because `ru` is the
  short name of a known language.
</Warning>

## Test and publish

Save the JSON file, then return to the game and open the menu.
[Hot reload](/cs2/api_reference/extensions/anatomy#hot-reload) reloads the whole
extension, translations included. You can also disable and enable the
extension.

When you publish, `langs/*.json` files are sent with the rest of the
extension. Make sure that `.neverloseignore` or the publish window does not
exclude them.
