Internationalization (i18n)

Overview

DS One includes built-in internationalization support, making it easy to create multi-language applications.

Setup

Load Translations

First, load your translation data:

import { loadTranslations, setLanguage } from 'ds-one';

// Define translations
const translations = {
  en: {
    welcome: 'Welcome',
    greeting: 'Hello',
    goodbye: 'Goodbye'
  },
  es: {
    welcome: 'Bienvenido',
    greeting: 'Hola',
    goodbye: 'Adiós'
  },
  fr: {
    welcome: 'Bienvenue',
    greeting: 'Bonjour',
    goodbye: 'Au revoir'
  }
};

// Load translations
await loadTranslations(translations);

// Set active language
setLanguage('en');

CDN Usage

<script type="module">
  import { loadTranslations, setLanguage }
    from 'https://cdn.jsdelivr.net/npm/ds-one@beta/dist/ds-one.bundle.js';

  // Load and set language
  await loadTranslations({
    en: { /* ... */ },
    es: { /* ... */ }
  });

  setLanguage('en');
</script>

Using Translations

In Components

Use the data-key attribute to specify which translation to use:

<text-v1 variant="heading" data-key="welcome"></text-v1>
<text-v1 variant="body" data-key="greeting"></text-v1>

Switching Languages

Create a language switcher:

<button-v1 onclick="changeLanguage('en')">English</button-v1>
<button-v1 onclick="changeLanguage('es')">Español</button-v1>
<button-v1 onclick="changeLanguage('fr')">Français</button-v1>

<script type="module">
  import { setLanguage } from 'ds-one';

  window.changeLanguage = (lang) => {
    setLanguage(lang);
  };
</script>

Loading from JSON

Load translations from external JSON files:

{
  "en": {
    "nav": {
      "home": "Home",
      "about": "About",
      "contact": "Contact"
    },
    "buttons": {
      "submit": "Submit",
      "cancel": "Cancel"
    }
  }
}

// Load from file
const response = await fetch('/translations.json');
const translations = await response.json();
await loadTranslations(translations);

Nested Keys

Support for nested translation keys:

const translations = {
  en: {
    nav: {
      home: 'Home',
      about: 'About'
    }
  }
};

// Use with dot notation
<text-v1 data-key="nav.home"></text-v1>

RTL Support

DS One automatically handles right-to-left (RTL) languages:

// RTL languages are automatically detected
setLanguage('ar'); // Arabic
setLanguage('he'); // Hebrew
setLanguage('fa'); // Persian

Language Detection

Automatically detect user’s preferred language:

import { setLanguage, detectLanguage } from 'ds-one';

// Get browser language
const userLang = detectLanguage();

// Set language based on detection
setLanguage(userLang);

Complete Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ds-one@beta/DS1/1-root/screen.css" />
  <script type="module" src="https://cdn.jsdelivr.net/npm/ds-one@beta/dist/ds-one.bundle.js"></script>
</head>
<body>
  <div id="app">
    <text-v1 variant="heading" data-key="title"></text-v1>
    <text-v1 variant="body" data-key="description"></text-v1>

    <button-v1 onclick="switchLang('en')">English</button-v1>
    <button-v1 onclick="switchLang('es')">Español</button-v1>
  </div>

  <script type="module">
    import { loadTranslations, setLanguage }
      from 'https://cdn.jsdelivr.net/npm/ds-one@beta/dist/ds-one.bundle.js';

    await loadTranslations({
      en: {
        title: 'Welcome to My App',
        description: 'This is a multilingual application'
      },
      es: {
        title: 'Bienvenido a Mi Aplicación',
        description: 'Esta es una aplicación multilingüe'
      }
    });

    setLanguage('en');

    window.switchLang = (lang) => setLanguage(lang);
  </script>
</body>
</html>

Best Practices

Keep translation keys organized and hierarchical
Use descriptive key names
Provide fallback translations
Test all supported languages
Handle missing translations gracefully