# Localization

Green Core has built in localization for English (default) and Swedish. This affects the built-in copy of the components.
For the rest of the copy in your application, you need to handle the localization separately. The localization in Green Core
is based on the `@lit/localize` library.

To use the localization features, you need to import and call the `gdsInitLocalization` function from Green Core:

```ts

const { setLocale } = gdsInitLocalization()
```

The current language can be set by calling the `setLocale` function that is returned from `gdsInitLocalization`:

```ts
setLocale('sv')
```

This can be called at any time, and it will cause all Green Core components on the page to re-render with the correct locale.

Note that `gdsInitLocalization()` can only be called once, so you need to set up a singleton of some kind (for example a service in Angular or `useEffect` in React) to make sure that
you only do this once per page load. If it is called twice, it'll throw an error the second time.

### List available locals

You can get a list of all available target locales by importing `targetLocales` from `@sebgroup/green-core/localization`:

```ts

// This will log an array of all available target locales
console.log(targetLocales)
```

Note that this list will not include the *source* locale, which is English in our case. Since we currently only support English and Swedish, the list will only contain `['sv']`.

## Additional locales

Green should have translations for all the required languages built-in, so if you are missing the locale that you need, please get in touch and we will help you add it.

If you find yourself in some edge case where you absolutely need a custom translation or locale, we got you covered too.

When calling `gdsInitLocalization` you can supply additional locales and templates:

```ts
const { setLocale, getLocale } = gdsInitLocalization({
  extraLocales,
  extraTemplates,
})
```

`extraLocales` is just an array of locale ids, like `['es', 'fr']` and `extraTemplates` needs to be a `Map` with locale id keys and `@lit/localize` templates as values. These templates can be generated using the `lit-localize` CLI. Check the [Lit website](https://lit.dev/docs/localization/overview/) for more info. You can also check the Green Core source code to see how it is done there.

## `@lit/localize` doesn't work with framework X. Why not use a framework agnostic solution?

Localization is one of those things that is often tightly coupled to the template engine of the framework you're using, which makes it tricky to provide a single framework agnostic solution.

The approach Green Core is going with is to provide built-in localization for standard copy in its components, but leave the rest of the app up to the consumer. The consumer-side requirements can be quite diverse from case to case. For example, translations may come from a CMS or some legacy back-end, so a lot of case-by-case flexibility is needed there, and it's hard to anticipate all of those requirements up front.

For the Green Core web components, `@lit/localize` makes sense, since it is a fairly simple and light-weight library, and the components use the lit-html template engine for their internal rendering needs.

So the mental model you should have here, is that you set up localization however you want in your application, and then in whichever function you set the locale, you also call `setLocale` from Green to keep the component language in sync.