Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Core: Update localization doc #1893

Merged
merged 1 commit into from
Dec 20, 2024
Merged

Core: Update localization doc #1893

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 31 additions & 10 deletions libs/core/src/storybook-docs/concepts/localization.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,26 +8,37 @@ Green Core has built in localization for English (default) and Swedish. This aff
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.

The current language can be set by calling the `setLocale` function from Green Core:
To use the localization features, you need to import and call the `gdsInitLocalization` function from Green Core:

```ts
import {
gdsInitLocalization,
targetLocales,
} from '@sebgroup/green-core/localization'
import { gdsInitLocalization } from '@sebgroup/green-core/localization'
const { setLocale } = gdsInitLocalization()
```

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

// log a list of available built-in locales
console.log(targetLocales)
```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
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
import { targetLocales } from '@sebgroup/green-core/localization'

// 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.
Expand All @@ -43,4 +54,14 @@ const { setLocale, getLocale } = gdsInitLocalization({
})
```

`extraLocales` is just an array of locale ids, like `['es', 'fr']` and `extraTempletes` 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 for more info. You can also check the Green Core source code to see how it is done there.
`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.
Loading