Language Support

Lager Guru supports multiple languages with a comprehensive internationalization (i18n) system. The platform currently supports German (de), English (en), and Bulgarian (bg).

Language Detection Priority

The system uses a priority-based language detection chain:

1. URL Prefix - Language code in URL path (/en/, /de/, /bg/)
2. User Preference - Language stored in user_settings.language
3. Tenant Default - Language set in tenants.language
4. Browser Language - Detected from browser settings
5. Fallback - Defaults to German (de)

User Language Preference

Users can set their preferred language using the language switcher component. The preference is stored in the user_settings table and persists across sessions.

Setting Language Preference

import { updateUserLanguage } from '@/lib/i18n-helpers';

// Update user language preference
await updateUserLanguage('en'); // or 'de', 'bg'

Tenant Language Defaults

Tenant administrators can set a default language for their organization. This language is used when:

• User has no language preference set
• User is not authenticated

Setting Tenant Language

-- Update tenant default language
UPDATE tenants
SET language = 'en'
WHERE id = 'tenant-uuid';

Language Switcher Component

The <LanguageSwitcher /> component is available throughout the application and allows users to change their language preference.

Usage

import { LanguageSwitcher } from '@/components/LanguageSwitcher';

function MyComponent() {
  return (
    <div>
      <LanguageSwitcher />
    </div>
  );
}

Translation Keys

All UI strings are stored in JSON translation files located in src/i18n/locales/{lang}/:

• common.json - Common strings used across the application
• landing.json - Landing page content
• admin.json - Admin dashboard strings
• safety.json - Safety module strings
• dashboard.json - Dashboard strings
• login.json - Login page strings

Using Translations in Components

Basic Translation

import { useTranslation } from 'react-i18next';

function MyComponent() {
  const { t } = useTranslation('common');
  
  return <h1>{t('welcome.title')}</h1>;
}

Translation with Namespace

import { useTranslation } from 'react-i18next';

function LandingPage() {
  const { t } = useTranslation('landing');
  
  return <h1>{t('hero.title')}</h1>;
}

Translation with Interpolation

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

// Translation key: "greeting": "Hello, {{name}}!"
<p>{t('greeting', { name: 'John' })}</p>

Adding New Languages

To add support for a new language:

1. Create translation files in src/i18n/locales/{lang}/
2. Add language to resources in src/i18n/config.ts
3. Update language switcher component
4. Add language to database CHECK constraints
5. Update VitePress documentation configuration

Custom Translations

Tenants can customize translations by:

• Setting tenant-specific language defaults
• Using the language switcher to override defaults
• Requesting custom translations from support

API Reference

getUserLanguage()

Returns the current user's language preference.

import { getUserLanguage } from '@/lib/i18n-helpers';

const lang = await getUserLanguage(); // 'de' | 'en' | 'bg' | null

getTenantLanguage()

Returns the tenant's default language.

import { getTenantLanguage } from '@/lib/i18n-helpers';

const lang = await getTenantLanguage(); // 'de' | 'en' | 'bg' | null

detectLanguage()

Detects language using the full priority chain.

import { detectLanguage } from '@/lib/i18n-helpers';

const lang = await detectLanguage(); // 'de' | 'en' | 'bg'

updateUserLanguage(language)

Updates the user's language preference.

import { updateUserLanguage } from '@/lib/i18n-helpers';

await updateUserLanguage('en'); // Updates user_settings.language

Database Schema

user_settings Table

CREATE TABLE user_settings (
  id uuid PRIMARY KEY,
  user_id uuid REFERENCES profiles(id),
  language text CHECK (language IN ('de', 'en', 'bg')),
  created_at timestamptz,
  updated_at timestamptz
);

tenants Table

ALTER TABLE tenants
ADD COLUMN language text DEFAULT 'de' 
CHECK (language IN ('de', 'en', 'bg'));

Troubleshooting

Language Not Changing

1. Check browser console for errors
2. Verify translation files exist for the language
3. Check user_settings table for language preference
4. Verify tenant language is set correctly

Missing Translations

If you see translation keys instead of text:

1. Check that the translation key exists in the JSON file
2. Verify the namespace is correct
3. Check browser console for missing key warnings

Best Practices

1. Always use translation keys - Never hardcode strings in components
2. Use descriptive keys - Use namespaced keys like landing.hero.title
3. Keep translations consistent - Use the same terminology across all languages
4. Test all languages - Verify UI works correctly in all supported languages
5. Update all languages - When adding new strings, update all language files

Related Documentation

• Multi-Tenant Guide
• System Settings
• API Reference