Internationalization — i18next in La Comanda

La Comanda ships with full English and Spanish translations powered by i18next and react-i18next. Every user-visible string in the application — navigation labels, page titles, table headers, KPI cards, error messages, and form placeholders — is resolved through a translation key rather than hardcoded in the component. This makes it straightforward to add new locales, correct copy, or extend the translation files without touching component source code.

Configuration

The i18n instance is initialised once in src/i18n.ts and imported at the app entry point so it is ready before any component mounts. Both locale files are bundled statically — there are no network requests for translation data at runtime.

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';

import enTranslation from './locales/en.json';
import esTranslation from './locales/es.json';

const resources = {
  en: {
    translation: enTranslation
  },
  es: {
    translation: esTranslation
  }
};

i18n
  .use(initReactI18next)
  .init({
    resources,
    lng: "es",           // default language is Spanish
    fallbackLng: "en",
    interpolation: {
      escapeValue: false // React already escapes values
    }
  });

export default i18n;

Key settings:

Setting	Value	Effect
`lng`	`"es"`	The app starts in Spanish on first load.
`fallbackLng`	`"en"`	If a key is missing from the active locale, the English value is used instead of showing the raw key.
`escapeValue`	`false`	Disables i18next’s HTML escaping — React’s JSX already handles this safely.
`resources`	Inline object	Both locale files are bundled at build time; no lazy-loading or HTTP fetching occurs.

Translation Namespaces

All keys for both locales live in the single default namespace (translation), organised into top-level section objects. The table below lists every section, its purpose, and the number of keys it contains.

Section key	Purpose	Example key
`sidebar`	Navigation sidebar labels	`sidebar.dashboard`, `sidebar.new_order`
`header`	Header bar labels	`header.search`, `header.manager`
`login`	Login page strings	`login.access`, `login.select_station`
`dashboard`	Dashboard KPI labels and controls	`dashboard.total_sales`, `dashboard.top_performers`
`tables`	Table view labels, status types, and activity strings	`tables.title`, `tables.types.Occupied`
`kitchen`	Kitchen monitor labels and ticket notes	`kitchen.urgent`, `kitchen.notes.medium_rare`
`inventory`	Inventory module labels and smart-recommendation copy	`inventory.low_alerts`, `inventory.gen_order`
`staff`	Staff control labels, role names, and filter options	`staff.active_staff`, `staff.on_break`
`settings`	Settings page labels across all four nav sections	`settings.language`, `settings.save`
`access_denied`	403 page labels and system-status fields	`access_denied.title`, `access_denied.level_admin`
`error403`	Error page strings (used by the `AccessDenied` page)	`error403.title`, `error403.return`

Using Translations in Components

Every component that displays text imports useTranslation from react-i18next and calls t() with the dotted key path. No other setup is required — the hook reads from the i18n instance initialised in i18n.ts.

import { useTranslation } from 'react-i18next';

export const MyComponent = () => {
  const { t } = useTranslation();
  return <h1>{t('dashboard.total_sales')}</h1>;
};

When the active language is Spanish this renders "Ventas Totales Hoy"; when English is active it renders "Total Sales Today".

Switching Language

Users change the interface language from the Settings page under System Preferences → Interface Language. The settings UI renders two styled <button> elements (English / Español) that call i18n.changeLanguage() on click and highlight the active locale by comparing against i18n.language. The change takes effect immediately across every mounted component without a page reload, because react-i18next subscribes all useTranslation consumers to i18n instance events.

const { t, i18n } = useTranslation();

// Switch to English
<button onClick={() => i18n.changeLanguage('en')}>
  {t('settings.english')}
</button>

// Switch to Spanish
<button onClick={() => i18n.changeLanguage('es')}>
  {t('settings.spanish')}
</button>

La Comanda does not currently persist the selected language to localStorage — the setting resets to the default ("es") on page reload. This is a known limitation. To add persistence, call localStorage.setItem('lng', lang) alongside i18n.changeLanguage(lang), and read that value as the lng option in i18n.ts at initialisation time.

Adding a Translation Key

Adding a new string to the application requires three steps.

Add the key to en.json

Open src/locales/en.json and add the new key under the appropriate section object. Create a new section object if the string belongs to a new feature area.

{
  "dashboard": {
    "total_sales": "Total Sales Today",
    "new_key": "My New Label"
  }
}

Add the same key to es.json

Open src/locales/es.json and add the Spanish equivalent under the same path. Omitting this step will not cause a runtime error — fallbackLng: "en" will silently serve the English value — but untranslated strings are a bug.

{
  "dashboard": {
    "total_sales": "Ventas Totales Hoy",
    "new_key": "Mi Nuevo Etiqueta"
  }
}

Use the key in the component

Call t() with the full dotted path wherever the string should appear.

import { useTranslation } from 'react-i18next';

export const MyComponent = () => {
  const { t } = useTranslation();
  return <span>{t('dashboard.new_key')}</span>;
};

Translation File Structure

Both locale files share the same key schema. Below is the full dashboard section from en.json, which covers the KPI cards and chart controls on the Analytics Dashboard page:

{
  "dashboard": {
    "title":            "Today's Overview",
    "subtitle":         "Monitor your restaurant's live performance.",
    "total_sales":      "Total Sales Today",
    "active_tables":    "Active Tables",
    "inventory_alerts": "Inventory Alerts",
    "avg_fulfillment":  "Avg. Fulfillment",
    "peak_volume":      "Peak Hour Volume",
    "peak_desc":        "Traffic flow per hour across all sections",
    "last_24h":         "Last 24 Hours",
    "last_7d":          "Last 7 Days",
    "top_performers":   "Top Performers",
    "view_insights":    "View All Staff Insights",
    "items_low":        "Items Low",
    "mins":             "mins",
    "view_all":         "View All"
  }
}

And the equivalent section from es.json:

{
  "dashboard": {
    "title":            "Resumen de Hoy",
    "subtitle":         "Supervisa el rendimiento en vivo de tu restaurante.",
    "total_sales":      "Ventas Totales Hoy",
    "active_tables":    "Mesas Activas",
    "inventory_alerts": "Alertas de Inventario",
    "avg_fulfillment":  "Prep. Promedio",
    "peak_volume":      "Volumen Hora Pico",
    "peak_desc":        "Flujo de tráfico por hora en todas las áreas",
    "last_24h":         "Últimas 24 Horas",
    "last_7d":          "Últimos 7 Días",
    "top_performers":   "Mejor Rendimiento",
    "view_insights":    "Ver todas las estadísticas de personal",
    "items_low":        "Ítems Bajos",
    "mins":             "mins",
    "view_all":         "Ver Todos"
  }
}

Frontend

Backend & Data

Internationalization — i18next in La Comanda

Configuration

Translation Namespaces

Using Translations in Components

Switching Language

Adding a Translation Key

Translation File Structure

Build docs developers (and LLMs) love

Frontend

Backend & Data

Documentation Index

​Configuration

​Translation Namespaces

​Using Translations in Components

​Switching Language

​Adding a Translation Key

​Translation File Structure

Build docs developers (and LLMs) love

Configuration

Translation Namespaces

Using Translations in Components

Switching Language

Adding a Translation Key

Translation File Structure