okp4/ui

import { ArgsTable, Meta, Story, Canvas, Preview, Props } from '@storybook/addon-docs'
import { LanguageSwitcher } from 'ui/atoms/languageSwitcher/LanguageSwitcher'
import { ThemeProvider } from 'ui/atoms/theme/ThemeProvider'
import { ThemeSwitcher } from 'ui/atoms/theme/ThemeSwitcher'

<Meta
  title="Atoms/LanguageSwitcher"
  component={LanguageSwitcher}
  decorators={[
    Story => (
      <ThemeProvider>
        <div className="story-theme-switcher">
          <ThemeSwitcher />
        </div>
        <div className="component-story-main language-switcher">
          <Story />
        </div>
      </ThemeProvider>
    )
  ]}
/>

# Language Switcher

> Allows the user to change the application language.

[![stability-unstable](https://img.shields.io/badge/stability-unstable-yellow.svg)](https://github.com/emersion/stability-badges#unstable)

## Description

`LanguageSwitcher` is used to offer multi-language support to users in order to improve their experience on the application.  
Its background color is transparent in order to offer an easy implementation.

## Overview

<Story
  name="Overview"
  args={{
    languages: [
      { name: 'English', lng: 'en' },
      { name: 'Français', lng: 'fr' }
    ]
  }}
>
  {args => (
    <div style={{ display: 'flex', justifyContent: 'center' }}>
      <LanguageSwitcher {...args} />
    </div>
  )}
</Story>

## Properties

<ArgsTable story="Overview" />

## Languages

The `LanguageSwitcher` comes with a `languages` mandatory property.  
This property must respect the `Languages` format which is an array of `Language`:

```ts
type Language = {
  readonly name: string
  readonly lng: string
}
```

##### **`example.tsx`**

```tsx
import { Languages } from '@okp4/ui'

export const MyExampleComponent: React.FC = () => {
  const allLanguages: Languages = [
    {
      "name": "English",
      "lng": "en"
    },
    {
      "name": "Français",
      "lng": "fr"
    },
      {
      "name": "Italiano",
      "lng": "it"
    }
  ]

  return <LanguageSwitcher languages={allLanguages} />

```

## Responsiveness

The component was built according to the principles of Responsive Web Design (see <a href="?path=/docs/guidelines-responsive-web-design--page">dedicated guideline</a>) in particular thanks to the use of media queries and a responsive grid.  
This allows the component to adapt to any screen size, from the smallest phone to a large desktop screen or television.

## Internationalization

`LanguageSwitcher` is provided with its defaults translation files (`languageSwitcher_en.json` and `languageSwitcher_fr.json`).  
It is possible to overwrite the translations or to add new translation keys if needed.  
Here are the keys and their english translations:

##### **`languageSwitcher_en.json`**

```json
{
  "languages": "Languages:"
}
```

Example of translation replacement or insertion:

- the file name must be the same, so here it has to be `languageSwitcher_en.json`
- the file format must be identical (same key names, curly brackets...)
- translation can be replaced by your own (overwrite)
- new key with associated translation can be added (extension)

##### **`languageSwitcher_en.json`**

```json
{
  "languages": "Update with your own translation here", // Translation overwrite
  "modify-language": "Write your own translation here" // Translation extension
}
```

Tsx usage:

```tsx
<p>{t('languageSwitcher:languages')}</p>
<p>{t('languageSwitcher:languages.modify-language')}</p>

```

The component was built according to the internationalization implementation: see <a href="?path=/docs/guidelines-internationalization--page">dedicated guideline</a>.

## Prerequisites

`LanguageSwitcher` is designed to be used on dark backgrounds because of its white text color.