kayrozen.com / smokesignal
forked from smokesignal.events/smokesignal
i18n+filtering fork - fluent-templates v2
fork atom
smokesignal / docs / USER_GUIDE.md
at main 7.2 kB view raw view code

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#

Accept-Language: fr-CA,fr;q=0.9,en;q=0.8

HTMX Requests#

<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 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