svelte-i18n/docs/Getting Started.md

Getting started

• 1. Installing
  • 1.1 VSCode extension
• 2. Locale dictionaries
• 3. Adding locale dictionaries
  • 3.1 Synchronous
  • 3.2 Asynchronous
• 4. Initializing
• 5. Localizing your app

1. Installing

First things first, let's install the necessary dependencies:

yarn add svelte-i18n

# if using rollup so we can import json files
yarn add -D @rollup/plugin-json

1.1 VSCode extension

If you're using VSCode and want to have your messages previewed alongside your components, checkout the i18n-ally and their FAQ to see how to set it up.

2. Locale dictionaries

A locale dictionary is a regular JSON object which contains message definitions for a certain language.

// en.json
{
  "page_title": "Page title",
  "sign_in": "Sign in",
  "sign_up": "Sign up"
}

// pt.json
{
  "page_title": "Título da página",
  "sign_in": "Entrar",
  "sign_up": "Registrar"
}

3. Adding locale dictionaries

There are two different ways of adding a new dictionary of messages to a certain locale:

3.1 Synchronous

Just import/require your locale .json files and pass them to the addMessages(locale, dict) method.

// 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

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 value change will automatically load the registered loaders for the new locale.

// 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

After populating your $dictionary with addMessages() or registering loaders via register(), you are ready to bootstrap the library. You can use init() to define the fallback locale, initial locale and other options of your app.

// src/i18n.js
import { register, init, getLocaleFromNavigator } 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

init({
  fallbackLocale: 'en',
  initialLocale: getLocaleFromNavigator(),
});
// starts loading 'en-US' and 'en'

Note: Make sure to call your i18n.js file on your app's entry-point. 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 store can help to only show your app after the initial load as shown in Locale.

In Sapper, you can use the preload static method together with waitLocale:

<!-- 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.

5. Localizing your app

After having the initial locale set, you're ready to start localizing your app. Import the $format method, or any of its aliases, to any component that needs to be translated. Then, just call $format passing the message id on your layout and voila! 🎉

<script>
  import { _ } from 'svelte-i18n'
</script>

<svelte:head>
  <title>{$_('page_title')}</title>
</svelte:head>

<nav>
  <a>{$_('sign_in')}</a>
  <a>{$_('sign_up')}</a>
</nav>

See Formatting to read about the supported message syntax and all the available formatters.