EverShelf/docs/wiki/Translations.md

🌍 Translations

EverShelf uses JSON translation files in the translations/ folder. The app auto-detects the browser language on load and falls back to English.

---

Currently Supported Languages

Language	File	Status
🇮🇹 Italian	translations/it.json	✅ Complete (base language)
🇬🇧 English	translations/en.json	✅ Complete
🇩🇪 German	translations/de.json	✅ Complete

---

Adding a New Language

1. Copy the base file

cp translations/it.json translations/fr.json

2. Translate all values

Open fr.json in your editor and translate every value (leave the keys unchanged).

{
  "app": {
    "name": "EverShelf",
    "loading": "Chargement..."   ← translate this
  },
  "nav": {
    "title": "🏠 EverShelf",    ← keep emoji, translate text
    "home": "Accueil"
  }
}

Rules:

• Never change the key names (left side of :)
• Keep {placeholder} tokens unchanged — they are replaced at runtime
  • Example: "toast.added": "Added {name} to {location}" — keep {name} and {location}
• Keep HTML tags if present (rare): <strong>, <br>
• Keep emojis (they are part of the UX design)
• Plurals: some keys have _one / _many variants — translate both

3. Register the language in the app

Open assets/js/app.js and find the SUPPORTED_LANGUAGES constant (near the top):

const SUPPORTED_LANGUAGES = ['it', 'en', 'de'];

Add your language code:

const SUPPORTED_LANGUAGES = ['it', 'en', 'de', 'fr'];

4. Add the language to translations/ badge list

Update the README.md badge:

[![i18n](https://img.shields.io/badge/i18n-IT%20%7C%20EN%20%7C%20DE%20%7C%20FR-orange.svg)](translations/)

5. Test

Open the app with ?lang=fr in the URL to force your language:

http://localhost:8080/?lang=fr

Check for missing keys — they will show the raw key name in the UI (e.g. nav.title).

6. Submit a PR

Open a pull request with your new translations/fr.json and the updated app.js line. See Contributing.

---

Translation Key Structure

The file is a nested JSON object. Here are the main sections:

Section	Description
app	General app strings
nav	Navigation labels
btn	Button labels
locations	Storage location names
categories	Product category names
dashboard	Dashboard section titles
inventory	Inventory page strings
use	Use/consume form strings
add	Add product form strings
scan	Barcode scanner strings
recipes	Recipe page strings
cooking	Cooking mode strings
shopping	Shopping list strings
log	Transaction log strings
settings	Settings page strings
scale	Scale integration strings
toast	Toast notification messages
error	Error messages
confirm	Confirmation dialog strings

---

Updating Existing Translations

If a new feature adds keys to it.json (the base), you need to add the same keys to en.json and de.json.

The CI pipeline validates that all language files contain the same keys — a missing key will fail the build.

To check locally:

node -e "
const it = require('./translations/it.json');
const en = require('./translations/en.json');
// flatten and compare keys...
"

Or just open a PR — CI will flag any missing keys automatically.

---

Language Detection Order

1. ?lang=xx URL parameter (forces a specific language)
2. localStorage.getItem('lang') (last manually selected language)
3. navigator.language / navigator.languages (browser preference)
4. Fallback: en

Users can change the language in Settings → Language.