Localization: Custom Translations & Setup Guide

Localization in shapez 2 is the system that provides in-game text and language selection, and it supports creating and loading custom translations for mods or personal use. Proper localization ensures players see names, descriptions, UI strings and error messages in their selected language and enables community translations and overrides.

Built-in languages and selection

• The game includes built-in localization files (e.g., translations-en-US.json) for supported languages.
• In-game language selection uses a language list; when you pick a language the corresponding translation file is used to show UI and game text.
• If a translation key is missing in the chosen language, the game falls back to the English translation for that key.

Custom translations (overrides)

• You can provide a custom translation file to override or extend the built-in translations.
• The custom file must follow the same translation file format as the built-in translations (for example, the structure used by translations-en-US.json).
• To enable custom translations, start the game with the command line argument:
  • --custom-translations
• When the --custom-translations flag is present, the game will look for your custom translations file and load it.

Translation file format and fields

• The custom translation file must be valid JSON and match the game's expected translation schema (keys mapped to translated strings).
• The file must include a valid LanguageCode entry. The LanguageTitle entry is ignored by the game; the UI will show the language as "Custom" in the language settings when a custom file is loaded.
• Any translation keys not provided in the custom file will continue to use the English defaults automatically.

How custom translations are applied

• Once loaded, the custom translations replace or supplement the built-in text. Only keys present in the custom file change; absent keys fall back to English.
• Because the UI lists custom translations as "Custom", users choosing that option will see the modified strings.

Best practices for creating translation files

• Start from the official translations-en-US.json as a template so you have all keys present.
• Keep the JSON structure and keys exactly as in the original; do not rename keys.
• Provide translations for all user-visible strings you want changed; leave other keys out to inherit English text.
• Test your file by launching the game with --custom-translations and selecting "Custom" in the language settings.
• Maintain consistent terminology and capitalization across keys to avoid confusing players.

Notes for modders

• Mods can ship their own translation files following the same format. If you want players to load mod translations as custom overrides, instruct them to use the --custom-translations flag and place the file where the game expects it.
• Because LanguageTitle is ignored and shown as "Custom", describe language specifics and origin inside the translation strings themselves if needed (for example, include a header string visible in the settings or main menu).

Troubleshooting

• If your custom translations do not appear, ensure:
  • The game was started with --custom-translations.
  • The JSON is valid and follows the game's translation schema.
  • LanguageCode in the file is a valid code.
• If a specific string remains in English, that key is likely missing from your custom file and is correctly falling back to the English translation.

This covers how shapez 2 handles localization, how to create and enable custom translation files, and practical tips for testing and troubleshooting.