sveltekit-i18n

A lightweight, powerful internationalization (i18n) library designed specifically for SvelteKit. This package combines @sveltekit-i18n/base with @sveltekit-i18n/parser-default to provide the quickest way to add multilingual support to your SvelteKit applications.

Why sveltekit-i18n?

• 🚀 SvelteKit-optimized – Built specifically for SvelteKit with full SSR support
• 📦 Minimal dependencies – Only ecosystem packages (base + parser-default)
• ⚡ Smart loading – Translations load only for visited pages (lazy loading)
• 🎯 Route-based – Automatic translation loading based on your routes
• 🔧 Flexible – Support for custom data sources (local files, APIs, databases)
• 🌐 Multiple parsers – Choose the syntax that fits your needs
• 📝 TypeScript – Complete type definitions and typed API
• 🎨 Component-scoped – Create multiple translation instances for different parts of your app

Installation

npm install sveltekit-i18n

Quick Start

1. Create your translation files

// src/lib/translations/en/common.json
{
  "greeting": "Hello, {{name}}!",
  "nav.home": "Home",
  "nav.about": "About"
}

// src/lib/translations/cs/common.json
{
  "greeting": "Ahoj, {{name}}!",
  "nav.home": "Domů",
  "nav.about": "O nás"
}

2. Setup i18n configuration

// src/lib/translations/index.js
import i18n from 'sveltekit-i18n';

/** @type {import('sveltekit-i18n').Config} */
const config = {
  loaders: [
    {
      locale: 'en',
      key: 'common',
      loader: async () => (await import('./en/common.json')).default,
    },
    {
      locale: 'cs',
      key: 'common',
      loader: async () => (await import('./cs/common.json')).default,
    },
  ],
};

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

3. Load translations in your layout

// src/routes/+layout.js
import { loadTranslations } from '$lib/translations';

/** @type {import('./$types').LayoutLoad} */
export const load = async ({ url }) => {
  const { pathname } = url;
  
  const initLocale = 'en'; // determine from cookie, user preference, etc.
  
  await loadTranslations(initLocale, pathname);
  
  return {};
};

4. Use translations in your components

<!-- src/routes/+page.svelte -->
<script>
  import { t } from '$lib/translations';
</script>

<h1>{$t('common.greeting', { name: 'World' })}</h1>

<nav>
  <a href="/">{$t('common.nav.home')}</a>
  <a href="/about">{$t('common.nav.about')}</a>
</nav>

Key Features

Route-based Loading

Load translations only for specific routes to optimize performance:

const config = {
  loaders: [
    {
      locale: 'en',
      key: 'home',
      routes: ['/'], // Load only on homepage
      loader: async () => (await import('./en/home.json')).default,
    },
    {
      locale: 'en',
      key: 'about',
      routes: ['/about'], // Load only on about page
      loader: async () => (await import('./en/about.json')).default,
    },
  ],
};

Placeholders and Modifiers

Use dynamic values in your translations:

{
  "welcome": "Welcome, {{name}}!",
  "items": "You have {{count:number;}} {{count; 1:item; default:items;}}."
}

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

<p>{$t('welcome', { name: 'Alice' })}</p>
<p>{$t('items', { count: 5 })}</p>

Documentation

📖 Complete Documentation Index – Find everything in one place

Quick Links

• 🚀 Getting Started Guide – 15-minute tutorial
• 🏗️ Architecture Overview – How everything works
• 📚 API Documentation – Complete reference
• ✨ Best Practices – Production-ready patterns
• 🔧 Troubleshooting – Common issues & FAQ

Examples

Explore working examples for different use cases:

• Multi-page app – Most common setup
• Locale-based routing – SEO-friendly URLs (e.g., /en/about)
• Component-scoped translations – Isolated translation contexts
• Custom parsers – Using ICU message format
• All examples – Complete list of examples

Advanced Usage

Need a different parser?

This library uses @sveltekit-i18n/parser-default. If you need ICU message format or want to create your own parser, use @sveltekit-i18n/base directly:

import i18n from '@sveltekit-i18n/base';
import parser from '@sveltekit-i18n/parser-icu';

const config = {
  parser: parser(),
  // ... rest of config
};

Learn more about parsers.

TypeScript Support

Full TypeScript support with complete type definitions for configuration and API:

import i18n, { type Config } from 'sveltekit-i18n';

const config: Config = {
  loaders: [
    // ... your loaders
  ],
};

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

Note: The library provides type definitions but does not automatically infer translation keys from your JSON files. You can create custom type-safe wrappers if needed (see Best Practices).

Contributing

We welcome contributions! Please read our Contributing Guide for details on:

• Development setup and workflow
• Git workflow (rebase-based, linear history)
• Commit guidelines (atomic commits)
• Pull request process
• Code standards and testing

Note: We're currently looking for maintainers. If you're interested in helping maintain this project, please reach out via this issue.

Changelog

See Releases for version history.

Related Packages

• @sveltekit-i18n/base – Core functionality with custom parser support
• @sveltekit-i18n/parser-default – Default message parser
• @sveltekit-i18n/parser-icu – ICU message format parser

License

MIT