Localization and Languages

Localization & Multi-Language Support

Bindarr offers comprehensive internationalization for both the application user interface and the underlying card printings.

---

UI Language vs. Card Printing Language

It is important to distinguish between two distinct language concepts in Bindarr:

Concept	Description	Controlled By
UI Language	The interface text across menus, buttons, modals, and tooltips.	User selection in Settings → Language.
Card Printing Language	The actual language a physical card is printed in (affecting card artwork, card title, and market pricing).	Selected per card during search, scan, or manual entry.

---

Supported UI Languages

Bindarr currently includes full community translations for 11 languages:

• English (en)
• Brazilian Portuguese (pt-BR)
• French (fr)
• German (de)
• Italian (it)
• Japanese (ja)
• Korean (ko)
• Russian (ru)
• Simplified Chinese (zh-CN)
• Traditional Chinese (zh-TW)
• Spanish (es)

---

Dual-Name Card Printing Model

Managing international trading cards presents a challenge: a Japanese collector may own a Japanese Charizard (リザードン), but wants to find it when searching "Charizard".

Bindarr solves this with a Dual-Name Architecture:

1. card_cache.name (Searchable Name): The canonical English card name. This ensures:
   • Searching "Pikachu" or "Black Lotus" finds printings in all 11 languages.
   • The 4-copy deck rule correctly links cards across languages.
   • Marketplace price proxies match properly.
2. card_cache.printed_name (Printed Name): The localized name printed on the physical card face.
3. Display Logic: The UI renders printed_name || name, displaying the authentic card face and localized title while keeping the card globally searchable.

---

Contributing UI Translations

Adding or updating a UI translation is simple and requires no backend coding:

1. Look in the frontend/src/locales/ directory.
2. Copy en.json to your target language code (e.g. nl.json for Dutch or pl.json for Polish).
3. Translate the string values following each key:

   {
     "common.save": "Opslaan",
     "common.cancel": "Annuleren",
     "scanner.title": "Kaartscanner"
   }

4. Preserve Placeholders: Do not translate variables inside curly braces (e.g. {count}, {name}).
5. Partial Translations: Any missing keys automatically fall back to English key-by-key without crashing.
6. Open a Pull Request on GitHub!

See docs/TRANSLATING.md for full guidelines.