svelte-i18n/docs/Getting Started.md

148 lines
4.3 KiB
Markdown
Raw Normal View History

2020-01-16 03:06:42 +01:00
### Getting started
2020-02-03 17:38:22 +01:00
<!-- @import "[TOC]" {cmd="toc" depthFrom=4 depthTo=6 orderedList=false} -->
<!-- code_chunk_output -->
- [1. Installing](#1-installing)
- [2. Locale dictionaries](#2-locale-dictionaries)
- [3. Adding locale dictionaries](#3-adding-locale-dictionaries)
- [3.1 Synchronous](#31-synchronous)
- [3.2 Asynchronous](#32-asynchronous)
- [4. Initializing](#4-initializing)
2020-02-03 17:38:22 +01:00
- [4. Localizing your app](#4-localizing-your-app)
<!-- /code_chunk_output -->
#### 1. Installing
First things first, let's install the necessary dependencies:
```sh
yarn add svelte-i18n
# if using rollup so we can import json files
yarn add -D @rollup/plugin-json
```
#### 2. Locale dictionaries
2020-01-16 03:06:42 +01:00
A locale dictionary is a regular JSON object which contains message definitions for a certain language.
```jsonc
// en.json
{
"page_title": "Page title",
2020-01-16 03:06:42 +01:00
"sign_in": "Sign in",
"sign_up": "Sign up"
2020-01-16 03:06:42 +01:00
}
// pt.json
{
"page_title": "Título da página",
"sign_in": "Entrar",
"sign_up": "Registrar"
2020-01-16 03:06:42 +01:00
}
```
#### 3. Adding locale dictionaries
2020-01-16 03:06:42 +01:00
There are two different ways of adding a new dictionary of messages to a certain locale:
2020-01-16 03:06:42 +01:00
##### 3.1 Synchronous
2020-01-16 03:06:42 +01:00
2020-01-21 14:11:10 +01:00
Just `import`/`require` your locale `.json` files and pass them to the [`addMessages(locale, dict)`](/docs/Methods.md#addmessage) method.
2020-01-16 03:06:42 +01:00
```js
// src/i18n.js
import { addMessages } from 'svelte-i18n'
import en from './en.json'
import enUS from './en-US.json'
import pt from './pt.json'
addMessages('en', en)
addMessages('en-US', enUS)
addMessages('pt', pt)
// en, en-US and pt are available
```
##### 3.2 Asynchronous
2020-01-16 03:06:42 +01:00
2020-08-25 16:17:43 +02:00
A more performant way to load your dictionaries is to register `loader` methods. This way, only the files registered to the current locale will be loaded. A `loader` is a method which must return a `Promise` that resolves to a `JSON` object. A [`$locale`](/docs/Locale.md#locale) value change will automatically load the registered loaders for the new locale.
2020-01-16 03:06:42 +01:00
```js
// src/i18n.js
import { register } from 'svelte-i18n'
register('en', () => import('./en.json'))
register('en-US', () => import('./en-US.json'))
register('pt', () => import('./pt.json'))
// en, en-US and pt are not available yet
```
#### 4. Initializing
2020-01-16 03:06:42 +01:00
2020-01-21 14:11:10 +01:00
After populating your [`$dictionary`](/docs/Dictionary.md) with [`addMessages()`](/docs/Methods.md#addmessages) or registering loaders via [`register()`](/docs/Methods.md#register), you are ready to bootstrap the library. You can use [`init()`](/docs/Methods.md#init) to define the fallback locale, initial locale and other options of your app.
2020-01-16 03:06:42 +01:00
```js
// src/i18n.js
import { register, init, getLocaleFromNavigator } from 'svelte-i18n'
2020-01-16 03:06:42 +01:00
register('en', () => import('./en.json'))
register('en-US', () => import('./en-US.json'))
register('pt', () => import('./pt.json'))
// en, en-US and pt are not available yet
init({
fallbackLocale: 'en',
initialLocale: getLocaleFromNavigator(),
2020-01-16 03:06:42 +01:00
})
// starts loading 'en-US' and 'en'
```
_**Note**: If you're using Sapper, remember to also call `init()` on your server side code (`server.js`)._
Since we're using `register`, and not `addMessages`, we need to wait for it's loaders to finish before rendering your app.
In **Svelte**, the [`$isLoading`](/docs/Locale.md#loading) store can help to only show your app after the initial load as shown in [Locale](/docs/Locale.md#loading).
In **Sapper**, you can use the `preload` static method together with `waitLocale`:
```svelte
<!-- src/_layout.svelte -->
<script context="module">
import { waitLocale } from 'svelte-i18n'
export async function preload() {
// awaits for the loading of the 'en-US' and 'en' dictionaries
return waitLocale()
}
</script>
```
Please note that the `fallbackLocale` is always loaded, independent of the current locale, since only some messages can be missing.
#### 4. Localizing your app
2020-01-21 14:11:10 +01:00
After having the initial locale set, you're ready to start localizing your app. Import the [`$format`](/docs/Formatting.md) method, or any of its aliases, to any component that needs to be translated. Then, just call [`$format`](/docs/Formatting.md) passing the message `id` on your layout and voila! 🎉
2020-01-16 03:06:42 +01:00
```svelte
<script>
import { _ } from 'svelte-i18n'
</script>
<svelte:head>
2020-02-06 18:37:27 +01:00
<title>{$_('page_title')}</title>
2020-01-16 03:06:42 +01:00
</svelte:head>
<nav>
<a>{$_('sign_in')}</a>
<a>{$_('sign_up')}</a>
</nav>
```
2020-01-21 14:11:10 +01:00
See [Formatting](/docs/Formatting.md) to read about the supported message syntax.