Joystick
@joystick.js/ui

component.language

How to access and set the user's language preference in Joystick components.

In Joystick, every component instance has access to a language property that contains the user's determined language preference. This language is automatically determined server-side during SSR and made available to all components on both the server and client.

Accessing the Language

The language is available as component.language in the render function:

ui/components/example/index.js

import joystick from '@joystick.js/ui';

const Example = joystick.component({
  render: (component) => {
    return `
      <div>
        <p>Current language: ${component.language}</p>
        <p>Welcome message in ${component.language}</p>
      </div>
    `;
  },
});

export default Example;

Language Preference Priority

Joystick determines the user's language preference using the following priority order:

  1. User Profile Language (user.language) - Highest priority

    • Set when a user is logged in and has a language preference in their profile

  2. Cookie Language (cookies.language) - Second priority

    • Set via browser cookie: document.cookie = "language=es"
    • Persists across browser sessions

  3. Browser Language (navigator.language) - Third priority

    • Automatically detected from the user's browser Accept-Language header
    • Falls back to browser's default language settings

  4. Default Language - Lowest priority

    • Configured in your app's settings/env.json file
    • Falls back to 'en' if no default is configured

Users can set their language preference by setting a browser cookie:

// Set language to Spanish
document.cookie = "language=es; expires=Fri, 31 Dec 2025 23:59:59 GMT; path=/";

// Set language to French  
document.cookie = "language=fr; expires=Fri, 31 Dec 2025 23:59:59 GMT; path=/";

// Using the cookies helper (available on component instances)
component.cookies.set('language', 'de', { expires: 365 }); // Expires in 1 year

Configuration

Configure your app's default language in settings/env.json:

settings/env.json

{
  "development": {
    "i18n": {
      "default_language": "en"
    }
  },
  "staging": {
    "i18n": {
      "default_language": "en"
    }
  },
  "production": {
    "i18n": {
      "default_language": "en"
    }
  }
}

Example: Language Switcher Component

Here's an example of a language switcher component that allows users to change their language preference:

ui/components/language_switcher/index.js

import joystick from '@joystick.js/ui';

const LanguageSwitcher = joystick.component({
  events: {
    'change select': (event, component) => {
      const selected_language = event.target.value;
      
      // Set the language cookie (expires in 1 year)
      component.cookies.set('language', selected_language, { expires: 365 });
      
      // Reload the page to apply the new language
      window.location.reload();
    },
  },
  
  render: (component) => {
    const languages = [
      { code: 'en', name: 'English' },
      { code: 'es', name: 'Español' },
      { code: 'fr', name: 'Français' },
      { code: 'de', name: 'Deutsch' },
    ];
    
    return `
      <div class="language-switcher">
        <label for="language-select">Language:</label>
        <select id="language-select">
          ${languages.map(lang => `
            <option value="${lang.code}" ${component.language === lang.code ? 'selected' : ''}>
              ${lang.name}
            </option>
          `).join('')}
        </select>
        <p>Current: ${component.language}</p>
      </div>
    `;
  },
});

export default LanguageSwitcher;

Working with Translations

The language property works seamlessly with Joystick's translation system. Use it to determine which translation files to load or to conditionally render content:

ui/components/welcome/index.js

import joystick from '@joystick.js/ui';

const Welcome = joystick.component({
  render: (component) => {
    const messages = {
      en: 'Welcome to our application!',
      es: '¡Bienvenido a nuestra aplicación!',
      fr: 'Bienvenue dans notre application!',
      de: 'Willkommen in unserer Anwendung!',
    };
    
    const message = messages[component.language] || messages.en;
    
    return `
      <div class="welcome">
        <h1>${message}</h1>
        <p>Language: ${component.language}</p>
      </div>
    `;
  },
});

export default Welcome;

Notes

  • The language preference is determined once per request on the server-side
  • Changes to language cookies require a page reload to take effect
  • The language property is read-only on component instances
  • Language codes should follow standard ISO 639-1 format (e.g., 'en', 'es', 'fr')
  • The language preference works for both authenticated and anonymous users