# LanguageButton

A toggle link that switches an article between two locales (English/Spanish by default), handling both embed and standalone URLs.

**Category:** Components/Text elements/LanguageButton

**Import:** `import { LanguageButton } from '@reuters-graphics/graphics-components'`

## Props

| Prop | Type | Default | Required | Description |
|------|------|---------|:--------:|-------------|
| `locale` | `string \| undefined` | `'en'` |  | The current locale of the article |
| `embedded` | `boolean` | `false` |  | Whether the article is embedded |
| `buttonOptions` | `{       locale: string;       label: string;     }` | `{
      locale: 'es',
      label: 'Leer en español',
    }` |  | Options for the language toggle button |
| `setUrl` | `() => string` | — |  | Custom function for handling URL changes for locales and embed versions. |

## Examples

### Demo

```svelte
<div style="display: flex; flex-direction: column; gap: 2rem;">
  {@render demoToggle(
    spanishLocale,
    'es',
    'ES',
    'Toggle between English and Spanish',
    () => {
      spanishLocale = spanishLocale === 'en' ? 'es' : 'en';
    }
  )}
  <LanguageButton locale={spanishLocale}></LanguageButton>
</div>
```

### CustomiseLanguage

```svelte
<div style="display: flex; flex-direction: column; gap: 2rem;">
  {@render demoToggle(
    frenchLocale,
    'fr',
    'FR',
    'Toggle between English and French',
    () => {
      frenchLocale = frenchLocale === 'en' ? 'fr' : 'en';
    }
  )}
  <LanguageButton
    locale={frenchLocale}
    buttonOptions={{
      locale: 'fr',
      label: 'Lire en français',
    }}
  ></LanguageButton>
</div>
```

## Documentation

# LanguageButton

The `LanguageButton` component creates a button that switches between an article written in English and another language.

> 💡**NOTE:** If a translated embed page does not exist, add `LanguageButton` conditionally so it only renders when `embedded` is `false`. This prevents a toggle button from appearing on the English embed page.

```svelte
<script>
  import { LanguageButton } from '@reuters-graphics/graphics-components';

  //  If using in the graphics kit, use `resolve` from `$app/paths` to ensure the toggle links to the correct URL
  import { resolve } from '$app/paths';

  // If using in the graphics kit, `embedded` prop will already be available in App.svelte.
  // Additionally, pass `locale = 'en'` as a prop
  let { embedded = false, locale = 'en' }: Props = $props();
</script>

<!-- Pass `embedded` to `LanguageButton` if the embed page is translated -->
<LanguageButton {locale} {embedded} {resolve} />
```

## Customise language and button label

By default, the toggle button will switch between English and Spanish, and the `buttonOptions` prop does not need to be passed. To customise the language and button label, pass the `locale` and the button `label` for the translation language as an object to the `buttonOptions` prop.

```svelte
<script>
  import { LanguageButton } from '@reuters-graphics/graphics-components';

  //  If using in the graphics kit, use `resolve` from `$app/paths` to ensure the toggle links to the correct URL
  import { resolve } from '$app/paths';

  // If using in the graphics kit, `embedded` prop will already be available in App.svelte.
  // Additionally, pass `locale = 'en'` as a prop
  let { embedded = false, locale = 'en' }: Props = $props();
</script>

<!-- Pass `buttonOptions` to customise the language and button label -->
<LanguageButton
  {locale}
  {embedded}
  {resolve}
  buttonOptions={{
    locale: 'fr',
    label: 'Lire en français',
  }}
/>
```

## Styling

Use global CSS to style the toggle button. The container div has the class `language-button` and the nested button has an id of `translate-button`.

```scss
:global(div.language-button) {
  /* Custom styles for the container div */

    button#translate-button {
        /* Custom styles for the toggle button */
    }
}

<Canvas of={LanguageButtonStories.CustomStyle} />

```

## Customising URLs

By default, the `LanguageButton` component will switch from English to the translated version of the main article by appending `/{locale}/` to the base URL. For example, if the English version of the article is at `www.example.com/article/`, the translated version will be at `www.example.com/article/{locale}/`.

If `embedded` is passed, it will switch between English and translated versions of the embed page by appending `/embeds/{locale}/page/` to the base URL. For example, if the English version of the embed page is at `www.example.com/article/embeds/en/page/`, the translated version will be at `www.example.com/article/embeds/{locale}/page/`.

To customise this, pass a function to the `setUrl` prop that returns the URLs you want to link to.

```svelte
<script>
  import { LanguageButton } from '@reuters-graphics/graphics-components';

  //  If using in the graphics kit, use `resolve` from `$app/paths` to ensure the toggle links to the correct URL
  import { resolve } from '$app/paths';

  // If using in the graphics kit, `embedded` prop will already be available in App.svelte.
  // Additionally, pass `locale = 'en'` as a prop
  let { embedded = false, locale = 'en' }: Props = $props();

  // Custom function to return the URLs for the toggle button
  const setUrl = () => {
    if (embedded) {
      if (locale === 'es') {
        // If we're in the non-English article, link to the English article
        return resolve('/embeds/en/custom-embed-url/');
      } else {
        return resolve('/embeds/es/custom-embed-url/');
      }
    } else {
      if (locale === 'es') {
        // If we're in the non-English article, link to the English article
        return resolve('/');
      } else {
        return resolve('/es/');
      }
    }
  };
</script>

<LanguageButton {locale} {embedded} {setUrl} />
```