Localization

Active contributors: AUTOMATIC1111

Purpose

Translate the webui interface into other languages. Localizations are JSON files that the front-end consumes and uses to swap text labels and tooltips at render time.

Where this lives now

In the very early days, localization JSON files lived in localizations/ and shipped with the repo. As of v1.6, localizations have been pulled out of the repository: localizations/ is empty in the tree, and translations are distributed as extensions through the standard extensions registry. The CODEOWNERS file documents this:

# if you were managing a localization and were removed from this file, this is because
# the intended way to do localizations now is via extensions.
# See: https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/Developing-extensions

The translation key list is generated by the JavaScript in javascript/localization.js; a localisation extension drops a localizations/<lang>.json into its directory and the framework picks it up.

How it works

graph TD
    Boot[localization.localizations()] --> Scan
    Scan --> CoreDir[localizations/<br/>(empty in tree, populated by user)]
    Scan --> ExtDirs[extensions*/<name>/localizations/]
    Scan --> Map[localization_map: name -> file]

    Page[Gradio page load] --> JS[javascript/localization.js]
    JS -->|fetch /localization/<name>| Server[modules/localization.py]
    Server -->|loads json file| JS
    JS -->|walk DOM| Replace[textContent + title attr swap]

Server side: modules/localization.py walks the configured directory and exposes a /localization/<name> route returning the JSON. Client side: when the user picks a language in Settings → User Interface → Localization, javascript/localization.js fetches the JSON, walks the DOM, and replaces visible text.

What translation keys look like

Each key is the original English string verbatim. Values are the translation in the target language:

{
  "Generate": "生成",
  "Sampling steps": "サンプリングステップ数",
  "title": "Stable Diffusion チェックポイントのモデルファイル",
  "...": "..."
}

Hovers and tooltips are translated via the title attribute.

"Localization" vs "Hints"

There's a separate, smaller dictionary of UI hints in javascript/hints.js. These are the tooltip strings shown when hovering over controls. They are English-only by default but localization JSONs can override them.

Adding a new language

1. Create an extension directory (or a fork of a known localisation).
2. Add localizations/<langname>.json.
3. Use the JS console to pull the current set of keys: localization.dumpTranslations() is exposed for this.
4. Translate the values.
5. Publish; users add it via Extensions → Available, restart, then pick the language in Settings.

Limitations

• No pluralisation, gender, or context — flat key/value maps only.
• Translations break when source strings change. When a label in ui.py is renamed, the corresponding key disappears and stays English until the localisation extension catches up.
• Settings labels in shared_options.py are translated like any other label, but the option names (the keys used in config.json and the API) are never translated.
• Right-to-left languages are not specially supported. CSS is LTR-only.

Integration points

• script_callbacks.on_ui_settings is the recommended way for an extension to register its own settings; those settings then become localisable just like core ones.
• For dynamic strings emitted by Python code (errors, status), translation does not apply — only static labels and the hints map go through localization.js.