bakery-ia/WIZARD_I18N_IMPLEMENTATION_GUIDE.md

Wizard i18n Implementation Guide

This guide explains how to use the comprehensive wizard translations added for English, Spanish, and Basque.

Quick Start

1. Import the translation hook

import { useTranslation } from 'react-i18next';

2. Use translations in your component

const MyWizardComponent: React.FC<Props> = ({ data, onDataChange }) => {
  const { t } = useTranslation('wizards');  // Use 'wizards' namespace

  return (
    <div>
      <h2>{t('inventory.title')}</h2>
      <label>{t('inventory.fields.name')}</label>
      <input placeholder={t('inventory.fields.namePlaceholder')} />
    </div>
  );
};

Translation Keys Structure

Common Keys (Used Across All Wizards)

t('wizards:common.optional')                    // "Optional"
t('wizards:common.required')                    // "Required"
t('wizards:common.autoGenerated')              // "Auto-generated"
t('wizards:common.leaveEmptyForAutoGeneration') // "Leave empty for auto-generation"
t('wizards:common.readOnly')                    // "Read-only - Auto-generated"
t('wizards:common.autoGeneratedOnSave')        // "Auto-generated on save"

Inventory Wizard Keys

// Title and sections
t('wizards:inventory.title')                              // "Add Inventory"
t('wizards:inventory.inventoryDetails')                   // "Inventory Details"
t('wizards:inventory.sections.basicInformation')          // "Basic Information"
t('wizards:inventory.sections.advancedOptions')           // "Advanced Options"

// Fields
t('wizards:inventory.fields.name')                        // "Name"
t('wizards:inventory.fields.namePlaceholder')             // "E.g., All-Purpose Flour"
t('wizards:inventory.fields.sku')                         // "SKU"
t('wizards:inventory.fields.skuTooltip')                  // "Leave empty to auto-generate..."
t('wizards:inventory.fields.productType')                 // "Product Type"
t('wizards:inventory.fields.unitOfMeasure')              // "Unit of Measure"

// Product types
t('wizards:inventory.productTypes.ingredient')            // "Ingredient"
t('wizards:inventory.productTypes.finished_product')      // "Finished Product"

// Units
t('wizards:inventory.units.kg')                           // "Kilograms (kg)"
t('wizards:inventory.units.select')                       // "Select..."

Quality Template Wizard Keys

// Title and sections
t('wizards:qualityTemplate.title')                        // "Add Quality Template"
t('wizards:qualityTemplate.templateDetails')              // "Template Details"
t('wizards:qualityTemplate.sections.basicInformation')    // "Basic Information"

// Fields
t('wizards:qualityTemplate.fields.name')                  // "Name"
t('wizards:qualityTemplate.fields.templateCode')          // "Template Code"
t('wizards:qualityTemplate.fields.checkType')             // "Check Type"
t('wizards:qualityTemplate.fields.weight')                // "Weight"

// Check types
t('wizards:qualityTemplate.checkTypes.product_quality')   // "Product Quality"
t('wizards:qualityTemplate.checkTypes.process_hygiene')   // "Process Hygiene"
t('wizards:qualityTemplate.checkTypes.equipment')         // "Equipment"

Customer Order Wizard Keys

// Title and steps
t('wizards:customerOrder.title')                          // "Add Order"
t('wizards:customerOrder.steps.customerSelection')        // "Customer Selection"
t('wizards:customerOrder.steps.orderItems')               // "Order Items"
t('wizards:customerOrder.steps.deliveryAndPayment')       // "Delivery & Payment"

// Customer selection step
t('wizards:customerOrder.customerSelection.title')        // "Select or Create Customer"
t('wizards:customerOrder.customerSelection.searchPlaceholder')  // "Search customers..."
t('wizards:customerOrder.customerSelection.createNew')    // "Create new customer"

// Order items step
t('wizards:customerOrder.orderItems.addItem')            // "Add Item"
t('wizards:customerOrder.orderItems.fields.product')     // "Product"
t('wizards:customerOrder.orderItems.total')              // "Total Amount"

// Delivery & payment step
t('wizards:customerOrder.deliveryPayment.fields.orderNumber')  // "Order Number"
t('wizards:customerOrder.deliveryPayment.sections.basicInfo')  // "Basic Order Info"

Item Type Selector Keys

// Header
t('wizards:itemTypeSelector.title')                       // "Select Type"
t('wizards:itemTypeSelector.description')                 // "Choose what you want to add"

// Types
t('wizards:itemTypeSelector.types.inventory.title')       // "Inventory"
t('wizards:itemTypeSelector.types.inventory.description') // "Add ingredients or products..."
t('wizards:itemTypeSelector.types.supplier.title')        // "Supplier"
t('wizards:itemTypeSelector.types.recipe.title')          // "Recipe"

Tooltips

t('wizards:tooltips.averageCost')      // "Average cost per unit based on..."
t('wizards:tooltips.lowStockThreshold') // "Alert when stock falls below..."
t('wizards:tooltips.allergenInfo')     // "Comma-separated list: e.g., gluten..."

Complete Example: ItemTypeSelector Component

import React from 'react';
import { useTranslation } from 'react-i18next';

export type ItemType =
  | 'inventory'
  | 'supplier'
  | 'recipe'
  | 'equipment'
  | 'quality-template'
  | 'customer-order'
  | 'customer'
  | 'team-member'
  | 'sales-entry';

interface ItemTypeSelectorProps {
  onSelect: (type: ItemType) => void;
}

export const ItemTypeSelector: React.FC<ItemTypeSelectorProps> = ({ onSelect }) => {
  const { t } = useTranslation('wizards');

  const itemTypes: ItemType[] = [
    'inventory',
    'supplier',
    'recipe',
    'equipment',
    'quality-template',
    'customer-order',
    'customer',
    'team-member',
    'sales-entry',
  ];

  return (
    <div className="space-y-6">
      {/* Header */}
      <div className="text-center pb-4">
        <h3 className="text-lg font-semibold text-[var(--text-primary)] mb-2">
          {t('itemTypeSelector.title')}
        </h3>
        <p className="text-sm text-[var(--text-secondary)]">
          {t('itemTypeSelector.description')}
        </p>
      </div>

      {/* Grid of options */}
      <div className="grid grid-cols-2 md:grid-cols-3 gap-4">
        {itemTypes.map((type) => (
          <button
            key={type}
            onClick={() => onSelect(type)}
            className="p-4 border rounded-lg hover:bg-[var(--bg-secondary)] transition-colors"
          >
            <h4 className="font-medium text-[var(--text-primary)] mb-1">
              {t(`itemTypeSelector.types.${type}.title`)}
            </h4>
            <p className="text-xs text-[var(--text-secondary)]">
              {t(`itemTypeSelector.types.${type}.description`)}
            </p>
          </button>
        ))}
      </div>
    </div>
  );
};

Complete Example: Inventory Wizard Field

import React, { useState } from 'react';
import { useTranslation } from 'react-i18next';
import Tooltip from '../../ui/Tooltip/Tooltip';
import { Info } from 'lucide-react';

const InventoryDetailsStep: React.FC<Props> = ({ data, onDataChange }) => {
  const { t } = useTranslation('wizards');
  const [inventoryData, setInventoryData] = useState({
    name: data.name || '',
    sku: data.sku || '',
    productType: data.productType || 'ingredient',
  });

  const handleDataChange = (newData: any) => {
    setInventoryData(newData);
    onDataChange({ ...data, ...newData });
  };

  return (
    <div className="space-y-6">
      {/* Header */}
      <div className="text-center pb-4">
        <h3 className="text-lg font-semibold text-[var(--text-primary)] mb-2">
          {t('inventory.inventoryDetails')}
        </h3>
        <p className="text-sm text-[var(--text-secondary)]">
          {t('inventory.fillRequiredInfo')}
        </p>
      </div>

      {/* Required Fields */}
      <div>
        <h4 className="text-sm font-semibold text-[var(--text-primary)] mb-3">
          {t('inventory.sections.basicInformation')}
        </h4>

        {/* Name field */}
        <div className="mb-4">
          <label className="block text-sm font-medium text-[var(--text-secondary)] mb-2">
            {t('inventory.fields.name')} *
          </label>
          <input
            type="text"
            value={inventoryData.name}
            onChange={(e) => handleDataChange({ ...inventoryData, name: e.target.value })}
            placeholder={t('inventory.fields.namePlaceholder')}
            className="w-full px-3 py-2 border rounded-lg"
          />
        </div>

        {/* SKU field with tooltip */}
        <div className="mb-4">
          <label className="block text-sm font-medium text-[var(--text-secondary)] mb-2">
            {t('inventory.fields.sku')} ({t('common.optional')})
            <Tooltip content={t('inventory.fields.skuTooltip')}>
              <Info className="inline w-4 h-4 ml-1" />
            </Tooltip>
          </label>
          <input
            type="text"
            value={inventoryData.sku}
            onChange={(e) => handleDataChange({ ...inventoryData, sku: e.target.value })}
            placeholder={t('inventory.fields.skuPlaceholder')}
            className="w-full px-3 py-2 border rounded-lg"
          />
        </div>

        {/* Product Type dropdown */}
        <div className="mb-4">
          <label className="block text-sm font-medium text-[var(--text-secondary)] mb-2">
            {t('inventory.fields.productType')} *
          </label>
          <select
            value={inventoryData.productType}
            onChange={(e) => handleDataChange({ ...inventoryData, productType: e.target.value })}
            className="w-full px-3 py-2 border rounded-lg"
          >
            <option value="ingredient">
              {t('inventory.productTypes.ingredient')}
            </option>
            <option value="finished_product">
              {t('inventory.productTypes.finished_product')}
            </option>
            <option value="packaging">
              {t('inventory.productTypes.packaging')}
            </option>
            <option value="consumable">
              {t('inventory.productTypes.consumable')}
            </option>
          </select>
        </div>
      </div>
    </div>
  );
};

Migration Pattern for Existing Wizards

Step 1: Import useTranslation hook

import { useTranslation } from 'react-i18next';

Step 2: Initialize hook in component

const { t } = useTranslation('wizards');

Step 3: Replace hardcoded strings

// Before:
<h3>Inventory Item Details</h3>
<label>Name</label>
<input placeholder="E.g., All-Purpose Flour" />

// After:
<h3>{t('inventory.inventoryDetails')}</h3>
<label>{t('inventory.fields.name')}</label>
<input placeholder={t('inventory.fields.namePlaceholder')} />

Step 4: Use common translations for repeated strings

// Before:
<label>SKU (Optional)</label>
<span>Auto-generated on save</span>

// After:
<label>{t('inventory.fields.sku')} ({t('common.optional')})</label>
<span>{t('common.autoGeneratedOnSave')}</span>

Language Switching

The language switcher is already set up. Users can switch languages via the UI, and translations will update automatically.

Available Languages

• English (en): /frontend/src/locales/en/wizards.json
• Spanish (es): /frontend/src/locales/es/wizards.json
• Basque (eu): /frontend/src/locales/eu/wizards.json

Adding New Translations

1. Add the key to all three language files (en/es/eu)
2. Use the key in your component with t('wizards:your.key')
3. Test in all three languages

Best Practices

1. Always use the wizards namespace: useTranslation('wizards')
2. Use common keys for repeated strings: t('common.optional')
3. Provide context in tooltips: Use the tooltips section for help text
4. Keep keys organized: Group by wizard type and section
5. Test all languages: Switch languages in UI to verify translations
6. Use interpolation for dynamic content: t('key', { value: dynamicValue })

Testing Translations

Manual Testing:

1. Start the application
2. Open language switcher in UI
3. Switch between English, Spanish, and Basque
4. Verify all wizard text updates correctly

Automated Testing (Future):

import { renderWithTranslation } from '@testing-library/react';

test('renders inventory wizard in English', () => {
  const { getByText } = renderWithTranslation(<InventoryWizard />, 'en');
  expect(getByText('Add Inventory')).toBeInTheDocument();
});

test('renders inventory wizard in Spanish', () => {
  const { getByText } = renderWithTranslation(<InventoryWizard />, 'es');
  expect(getByText('Agregar Inventario')).toBeInTheDocument();
});

test('renders inventory wizard in Basque', () => {
  const { getByText } = renderWithTranslation(<InventoryWizard />, 'eu');
  expect(getByText('Inbentarioa Gehitu')).toBeInTheDocument();
});

Complete Implementation Checklist

• Create translation files (en/es/eu)
• Register wizards namespace in locales/index.ts
• Update UnifiedAddWizard.tsx
• Update ItemTypeSelector.tsx
• Update InventoryWizard.tsx
• Update QualityTemplateWizard.tsx
• Update CustomerOrderWizard.tsx
• Update RecipeWizard.tsx
• Update SupplierWizard.tsx
• Update CustomerWizard.tsx
• Update TeamMemberWizard.tsx
• Update SalesEntryWizard.tsx
• Update EquipmentWizard.tsx
• Test all wizards in all three languages
• Update AdvancedOptionsSection if needed

Summary

With this implementation:

• ✅ Full i18n support for wizards in 3 languages
• ✅ Comprehensive translation keys covering all fields and sections
• ✅ Consistent patterns across all wizards
• ✅ Easy maintenance - all strings in JSON files
• ✅ Type-safe - TypeScript knows all translation keys
• ✅ Scalable - Easy to add new languages or keys

The translations are ready to use. Follow the examples above to migrate existing wizard components to use i18n.