sveltekit-i18n

sveltekit-i18n is a tiny, dependency-less library built for Svelte and SvelteKit.

NOTE: This project is currently in beta as long as tests are missing. Also API may vary until 1.0.0 is released...

Key features

✅ Simple API
✅ SvelteKit ready
✅ SSR support
✅ Custom data sources – no matter if you are using local files or remote API to get your translations
✅ Module-based – your translations are loaded only in time they are really needed (and only once!)
✅ TS support
✅ No dependencies

TODO

• documentation
• examples
• tests

Usage

Setup translations.js in your lib folder...

import i18n from 'sveltekit-i18n';

export const config = ({
  loaders: [
    {
      locale: 'en',
      key: 'common',
      loader: async () => (
        await import('./en/common.json')
      ).default,
    },
    {
      locale: 'en',
      key: 'home',
      routes: ['/'],
      loader: async () => (
        await import('./en/home.json')
      ).default,
    },
    {
      locale: 'en',
      key: 'about',
      routes: ['/about'],
      loader: async () => (
        await import('./en/about.json')
      ).default,
    },
    {
      locale: 'cs',
      key: 'common',
      loader: async () => (
        await import('./cs/common.json')
      ).default,
    },
    {
      locale: 'cs',
      key: 'home',
      routes: ['/'],
      loader: async () => (
        await import('./cs/home.json')
      ).default,
    },
    {
      locale: 'cs',
      key: 'about',
      routes: ['/about'],
      loader: async () => (
        await import('./cs/about.json')
      ).default,
    },
  ],
});

export const { t, locale, locales, loading, loadTranslations } = new i18n(config);

...include your translations in __layout.svelte...

<script context="module">
  import { loadTranslations } from '$lib/translations';

  export const load = async ({ page }) => {
    const { path } = page;

    const locale = 'en'; // get from cookie or user session...
    await loadTranslations(locale, path);

    return {};
  }
</script>

...and use your placeholders within pages and components.

<script>
  import { t } from '$lib/translations';

  const pageName = 'This page is Home page!';
</script>

<div>
  <!-- you can use {{placeholders}} in your definitions -->
  <h2>{$t('common.page', { pageName })}</h2>
  <p>{$t('home.content')}</p>
</div>

Config

loaders: Array<{ locale: string; key: string; loader: () => Promise<Record<any, any>>; routes?: Array<string | RegExp>; }>

You can use loaders to define your asyncronous translation load. All loaded data are stored so loader is triggered only once – in case there is no previous version of the translation. Each loader can include:

locale: string – locale (e.g. en, de) which is this loader for.

key: string – represents the translation module. This key is used as a translation prefix so it should be module-unique. You can access your translation later using $t('key.yourTranslation'). It shouldn't include . (dot) character.

loader:() => Promise<Record<any, any>> – is a function returning a Promise with translation data. You can use it to load files locally, fetch it from your API etc...

routes?: Array<string | RegExp> – can define routes this loader should be triggered for. You can use Regular expressions too. For example [/\/.ome/] will be triggered for /home and /rome route as well (but still only once). Leave this undefined in case you want to load this module with any route (useful for common translations).

initialLocale?: string

If you set this parameter, translations will be initialized immediately using this locale.