# smokesignal User Guide

## Language and Internationalization

smokesignal provides a comprehensive internationalization experience with support for multiple languages and automatic language detection.

### Supported Languages

- **English (US)**: `en-US` - Default language
- **French (Canadian)**: `fr-CA` - Full translation with gender support

### Automatic Language Detection

smokesignal automatically detects your preferred language using several methods:

1. **Browser Language Preference**: Reads your browser's `Accept-Language` header
2. **URL Parameters**: Language can be specified via `?lang=fr-ca` parameter
3. **Session Storage**: Language preference is saved for your session
4. **Fallback**: Defaults to English if no preference is detected

### Switching Languages

#### Method 1: Browser Language Settings

**Chrome:**
1. Open Chrome Settings (chrome://settings/)
2. Click "Advanced" → "Languages"
3. Add your preferred language (French Canadian)
4. Move it to the top of the list
5. Restart your browser and visit smokesignal

**Firefox:**
1. Open Firefox Settings (about:preferences)
2. Scroll to "Language and Appearance"
3. Click "Choose" next to "Request websites in this language"
4. Add "French (Canada)" [fr-ca]
5. Move it to the top priority
6. Restart Firefox

**Safari:**
1. Open System Preferences → Language & Region
2. Add French (Canada) to preferred languages
3. Restart Safari

#### Method 2: URL Parameter

Add the language parameter to any smokesignal URL:
```
https://your-smokesignal-site.com/events?lang=fr-ca
```

#### Method 3: Language Switcher (if available)

Some smokesignal deployments include a language switcher in the navigation. Look for:
- Language flags or codes (EN/FR)
- A dropdown menu with language options
- "Language" or "Langue" links

### Mobile Device Language Configuration

#### iOS (iPhone/iPad)
1. Open Settings app
2. Tap "General" → "Language & Region"
3. Tap "iPhone Language" or "iPad Language"
4. Select "Français (Canada)" if available
5. Confirm the change and restart your device

#### Android
1. Open Settings app
2. Tap "System" → "Languages & input" → "Languages"
3. Tap "Add a language"
4. Select "Français (Canada)"
5. Drag it to the top of the list
6. Restart your browser app

### Understanding Translated Content

#### Event Filtering Interface

When using French Canadian, you'll see:
- **Search placeholder**: "Rechercher par nom ou description"
- **Date filters**: "Date de début" / "Date de fin"
- **Location**: "Lieu"
- **Categories**: "Catégories"
- **Sort options**: "Trier par"

#### Event Status and Formats

Event statuses and formats are automatically translated:
- **Active** → **Actif**
- **Draft** → **Brouillon**
- **In-Person** → **En personne**
- **Virtual** → **Virtuel**
- **Hybrid** → **Hybride**

#### Facet Counts and Pluralization

smokesignal uses intelligent pluralization:
- **English**: "1 event" vs "5 events"
- **French**: "1 événement" vs "5 événements"

### Troubleshooting Language Issues

#### Language Not Changing

**Problem**: Website remains in English despite browser settings
**Solutions**:
1. Clear browser cache and cookies
2. Ensure French Canadian (fr-CA) is selected, not just "French"
3. Try the URL parameter method: `?lang=fr-ca`
4. Check that JavaScript is enabled
5. Refresh the page completely (Ctrl+F5 or Cmd+Shift+R)

#### Partial Translation

**Problem**: Some text appears in English while other text is in French
**Solutions**:
1. This is normal - some dynamic content may not be translated
2. Report missing translations to the site administrator
3. Administrative and error messages may remain in English

#### Wrong Language Detected

**Problem**: Site shows French when you want English
**Solutions**:
1. Add English to the top of your browser's language preferences
2. Use URL parameter: `?lang=en-us`
3. Clear browser data and reload

#### HTMX Requests Showing Wrong Language

**Problem**: Dynamic content loads in wrong language
**Solutions**:
1. Ensure JavaScript is enabled
2. Check that your browser supports modern web standards
3. Try disabling browser extensions temporarily
4. Clear browser cache

### Gender-Aware Content (French Canadian)

When using French Canadian, smokesignal may display personalized content based on gender preferences:

- **Masculine forms**: "Créé par un utilisateur"
- **Feminine forms**: "Créée par une utilisatrice"
- **Neutral forms**: "Créé par une personne"

Gender preferences can be set in your user profile settings.

### Performance Considerations

#### Language Loading

- Translations are pre-compiled for fast loading
- No network requests needed for language switching
- Cached content improves performance

#### Cache Behavior

- Each language has separate cache entries
- Switching languages may require fresh data loading
- Search results are cached per language

### Accessibility

#### Screen Readers

smokesignal's i18n implementation supports screen readers:
- Proper `lang` attributes on HTML elements
- Translated aria-labels and descriptions
- Voice synthesis works with both languages

#### High Contrast Mode

All translated text maintains proper contrast ratios in high-contrast modes.

### API Usage with Languages

If you're integrating with smokesignal's API, you can specify language preferences:

#### HTTP Headers
```http
Accept-Language: fr-CA,fr;q=0.9,en;q=0.8
```

#### HTMX Requests
```html
<div hx-get="/events" 
     hx-headers='{"Accept-Language": "fr-CA"}'>
</div>
```

### Feedback and Contributions

#### Reporting Translation Issues

1. Note the specific page and text that needs translation
2. Include your browser and language settings
3. Provide the English text and suggested French translation
4. Submit via the feedback form or GitHub issues

#### Contributing Translations

Translations are stored in Fluent (`.ftl`) files:
- English: `/i18n/en-us/`
- French: `/i18n/fr-ca/`

See the [Contributing Guide](CONTRIBUTING.md) for translation contribution guidelines.

### Advanced Features

#### RTL Language Support

While not currently implemented, smokesignal's architecture supports future RTL languages like Arabic or Hebrew.

#### Regional Variants

The system can support regional variants like:
- `fr-FR` (France French)
- `en-GB` (British English)
- `es-MX` (Mexican Spanish)

#### Custom Date/Time Formatting

Date and time formats automatically adjust based on locale:
- **en-US**: MM/DD/YYYY, 12-hour time
- **fr-CA**: DD/MM/YYYY, 24-hour time

### Best Practices for Multilingual Use

1. **Set browser language properly**: Use the full locale code (fr-CA, not just fr)
2. **Keep languages consistent**: Don't mix language settings across devices
3. **Report issues**: Help improve translations by reporting problems
4. **Clear cache regularly**: Prevents old translations from persisting
5. **Test both languages**: If you're creating content, preview in both languages

### Privacy and Language Data

smokesignal's language detection is privacy-friendly:
- Language preferences are stored locally or in session
- No personal language data is transmitted to third parties
- Browser language headers are standard and anonymous