#Documentation Index

Complete documentation for the sveltekit-i18n ecosystem, covering v3: one reactive instance built on Svelte 5 runes, no stores, and the parser wired in — npm install sveltekit-i18n is the whole install.

Upgrading from v2? Go straight to Upgrading from v2 and the migration table.

#🚀 Getting Started

New to sveltekit-i18n? Start here:

#Getting Started Guide

A SvelteKit app from nothing to multilingual, in eight steps

• Requirements and installation – Svelte 5, Node 22 / Bun 1.2 / Deno 2, ESM-only
• Basic concepts – locales, keys, loaders, namespaces, the instance
• Your first multilingual app – translation files, exporting the config, resolving the visitor's locale, one instance per request, the snapshot, Svelte context, components
• Route-based loading and switching locales
• Placeholders and modifiers, including parserOptions
• TypeScript and testing components

Perfect for: first-time users, quick setup

#📚 Core Documentation

#Architecture Overview

Understanding how everything works

• Package overview and relationships – core, parser, this package; composition rather than inheritance, and the parser extension
• The reactive engine – runes, and why the core ships its rune modules uncompiled
• Data flow – construction, loading, translation, locale switch
• Loading strategy – route matching, load-once, deduplication, cache and invalidation
• Instance lifetime – per-request instances, snapshot(), destroy()
• Core concepts, when to use each package, performance

Perfect for: understanding internals, making architecture decisions

#API Documentation

Complete reference for sveltekit-i18n

• Installation and packaging – ESM-only, one install, bundler requirements
• Configuration – loaders, translations, initLocale, fallbackLocale, fallbackValue, preprocess, sanitizeLocales, cache, log, schema, extensions
• Parser options – modifierDefaults, customModifiers, onReport
• The instance – reactive properties, reactive functions, promise-returning methods, synchronous methods
• Message format, exported types, utilities
• TypeScript, extensions, SSR, testing
• Migrating from v2

Perfect for: day-to-day development, looking up specific APIs

#@sveltekit-i18n/base API Documentation

The canonical reference for every member this package inherits

• Configuration and loaders
• Instance properties and methods
• Server-side rendering
• The parser contract – for building on the core with a different parser
• TypeScript

Perfect for: member-level detail, or using the core with a custom parser

#✨ Best Practices

#Best Practices Guide

Recommended patterns for production apps

• Instance ownership – per-request instances, the module-level singleton hazard, destroy(), why value properties must not be destructured
• Awaiting loads – await the matching load instead of polling loading
• SSR and CSR – snapshot, hydration, no flash of untranslated content
• Organization and key naming
• Performance – lazy loading, preloading, cache and invalidate()
• TypeScript – schema, one payload type, locale completion, custom modifier props
• Extensions – the pipe, and getting the $t surface back
• Component-scoped – isolated translation contexts
• Library authors – shipping translations with a package
• Dynamic routes – locale-based routing patterns
• Content management – CMS, API and database sources
• Testing – a real instance instead of a mock
• Production – logging, parser reports, loader failures, monitoring

Perfect for: building production applications, scaling your i18n implementation

#🔧 Troubleshooting

#Troubleshooting & FAQ

Solutions to common problems

• Upgrading from v2 – $t is not a store, destructured values that never update, the removal of .get() / .set() / .subscribe() / toPromise() / getTranslationProps(), and instanceof
• Setup and packaging – $state is not defined, two copies of the core, ERR_REQUIRE_ESM
• Common issues – translations not loading, keys instead of values, flashing content, route matching, locale not changing, stale translations, one visitor's locale in another's page, silent parser reports, TypeScript errors, tests, performance
• Debugging tips – inspect translations, enable debug logging, open the report channel, test a loader
• FAQ – 17 common questions
• Known limitations – what to be aware of

Perfect for: fixing issues, understanding limitations

#🎨 Parser Documentation

Message interpolation lives in a parser. This package wires one; the core takes any parser that satisfies base's parser contract.

#@sveltekit-i18n/parser-curly

The parser wired into this package

• Placeholders {{name}}, default values, nested placeholders, escaping
• Modifiers (number, date, currency, ago, …) and comparisons
• Custom modifiers, modifier defaults and the report channel — all reachable here through parserOptions
• Implements the Curly Message Format

#@sveltekit-i18n/parser-icu

ICU message format

For an application that wants ICU syntax, built on @sveltekit-i18n/base directly — this package fills the parser slot itself and cannot take another parser.

#Parsers Overview

The parser monorepo, and writing your own

#💡 Examples

#All Examples

Working code you can learn from

Eight standalone applications on v3: locale routing (URL parameter, path prefix, static adapter, default locale unprefixed), per-request negotiation from a cookie and Accept-Language, component-scoped translations rendered on the client and seeded through snapshot(), and t() inside Markdown routes.

#📦 Package Documentation

#This Package

• sveltekit-i18n README – overview and quick start
• Contributing guide – repository layout, workflow, tests
• Releases – version history

#The Family

• @sveltekit-i18n/base – the core; state, loading, caching, route matching, preprocessing (releases)
• @sveltekit-i18n/parser-curly and @sveltekit-i18n/parser-icu (releases)
• Extensions – official adapters for the config.extensions pipe, including @sveltekit-i18n/extension-stores (the $t / $locale / $loading surface)
• Curly Message Format – the message format specification

base, parsers and extensions release aligned at 3.0.0; sveltekit-i18n last.

#🎯 Quick Links by Task

#I want to...

#Learn the basics

→ Getting Started Guide

#Upgrade an app from v2

→ Upgrading from v2 and the migration table

#Get $t back

→ Best Practices: Extensions

#Understand how it works

→ Architecture Overview

#Look up an API

→ API Documentation or base API Documentation

#Render on the server without leaking a visitor's locale

→ API Docs: SSR or Best Practices: Instance Ownership

#Build a production app

→ Best Practices Guide

#Fix an issue

→ Troubleshooting Guide

#See working code

→ Examples

#Write a custom modifier or open the report channel

→ API Docs: Parser options or parser-curly

#Use a different message format

→ Architecture: When to Use Each Package

#Create locale-based URLs

→ Best Practices: Dynamic Routes

#Optimize performance

→ Best Practices: Performance or Architecture: Performance

#Type my keys and payloads

→ Best Practices: TypeScript or API Docs: TypeScript

#Load from an API or database

→ Best Practices: Content Management or base API: Loaders

#Test components that translate

→ Best Practices: Testing or Getting Started: Testing

#Deploy to production

→ Best Practices: Production

#📖 Reading Order

#For Beginners

1. Getting Started Guide – learn by building
2. API Documentation – the surface, member by member
3. Best Practices – level up your implementation

#For Upgraders

1. Upgrading from v2 – the first-day errors
2. Migrating from v2 – the old member, the new one
3. Best Practices: Instance Ownership – what per-request instances change

#For Advanced Users

1. Architecture Overview – understand the system
2. base API Documentation – deep dive
3. Parsers and Extensions – custom message formats and custom surfaces

#For Troubleshooting

1. Troubleshooting Guide – find your issue
2. FAQ – common questions
3. GitHub Issues – get help

#🤝 Contributing

Interested in contributing to sveltekit-i18n?

• Contributing Guide – setup, workflow, tests, PRs
• GitHub Repository – main library, and the shared issue tracker for the whole family
• Issues – report bugs, request features
• Discussions – ask questions, share ideas

#📄 License

MIT License – See individual repositories for details.

Can't find what you're looking for? Check the Troubleshooting Guide for how to get help.