Internationalization (i18n)

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@alpha/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:

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

<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@alpha/DS1/1-root/one.css"
    />
    <script
      type="module"
      src="https://cdn.jsdelivr.net/npm/ds-one@alpha/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>

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

    <script type="module">
      import {
        loadTranslations,
        setLanguage,
      } from "https://cdn.jsdelivr.net/npm/ds-one@alpha/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