Documentation Index

December 2, 2025 · View on GitHub

Complete documentation for the sveltekit-i18n ecosystem. Whether you're just getting started or need detailed API references, you'll find everything here.

🚀 Getting Started

New to sveltekit-i18n? Start here:

Getting Started Guide

Time to complete: 15 minutes

Step-by-step tutorial that walks you through:

  • Installing the library
  • Creating your first translations
  • Loading translations in your app
  • Using translations in components
  • Switching between languages

Perfect for: First-time users, quick setup

📚 Core Documentation

Architecture Overview

Understanding how everything works

Learn about:

  • Package relationships (base, lib, parsers)
  • Data flow (configuration → loading → translation)
  • Loading strategies (route-based, SSR/CSR)
  • When to use each package
  • Performance considerations

Perfect for: Understanding internals, making architecture decisions

API Documentation

Complete reference for sveltekit-i18n

Includes:

  • All configuration options with examples
  • Parser options (modifierDefaults, customModifiers)
  • Instance properties and methods (t,t, locale, etc.)
  • Message format syntax
  • TypeScript usage

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

@sveltekit-i18n/base API Documentation

API reference for base package

Detailed documentation for:

  • Core configuration options
  • Loaders (local files, APIs, databases)
  • Preprocessing strategies
  • All stores and methods
  • Advanced use cases

Perfect for: Using base package with custom parsers

✨ Best Practices

Best Practices Guide

Recommended patterns for production apps

Covers:

  • Organization – File structure, naming conventions
  • Performance – Lazy loading, caching, bundle optimization
  • TypeScript – Typed configuration, custom type-safe patterns
  • SSR/CSR – Server-side rendering considerations
  • Component-scoped – Isolated translation contexts
  • Dynamic routes – Locale-based routing patterns
  • Content management – CMS and database integration
  • Testing – Mocking translations, test strategies
  • Production – Deployment, monitoring, error handling

Perfect for: Building production applications, scaling your i18n implementation

🔧 Troubleshooting

Troubleshooting & FAQ

Solutions to common problems

Includes:

  • Common Issues with step-by-step solutions:
    • Translations not loading
    • Keys displayed instead of values
    • Flashing content (FOUC)
    • Route-based loading problems
    • Locale not changing
    • TypeScript errors
    • SSR errors
    • Performance issues
  • Debugging tips – Inspect stores, test loaders, enable logging
  • FAQ – 15+ frequently asked questions
  • Known limitations – What to be aware of

Perfect for: Fixing issues, understanding limitations

🎨 Parser Documentation

Parsers Overview

Available parsers and creating custom ones

Learn about:

  • Choosing between parsers
  • Parser comparison
  • Creating custom parsers
  • Parser integration with base

@sveltekit-i18n/parser-default

Default parser with placeholders and modifiers

Features:

  • Simple placeholder syntax: {{name}}
  • Built-in modifiers: number, date, currency, ago
  • Conditionals: {{count; 1:item; default:items;}}
  • Comparison operators: eq, ne, lt, gt, lte, gte
  • Custom modifiers
  • No external dependencies

@sveltekit-i18n/parser-icu

ICU message format parser

Features:

  • Industry-standard ICU syntax
  • Advanced pluralization
  • Select format (gender, etc.)
  • Number/date/time formatting
  • Comprehensive Intl support

💡 Examples

All Examples

Working code you can learn from

Browse examples by use case:

Basic Examples

Routing Examples

Advanced Examples

Parser Examples

Configuration Examples

  • Loaders – Different loader configurations
  • Preprocess – Preprocessing strategies

Each example includes:

  • Complete working code
  • Live demo on Netlify
  • README with explanations

📦 Package Documentation

Main Library

Core Package

Parsers

I want to...

Learn the basics

→ Getting Started Guide

Understand how it works

→ Architecture Overview

Look up an API

→ API Documentation or Base API Documentation

Build a production app

→ Best Practices Guide

Fix an issue

→ Troubleshooting Guide

See working code

→ Examples

Use a different parser

→ Parsers Overview

Create locale-based URLs

→ Locale Router Example or Best Practices: Dynamic Routes

Optimize performance

→ Best Practices: Performance or Architecture: Performance

Add TypeScript

→ Best Practices: TypeScript or API Docs: TypeScript

Load from API/database

→ Best Practices: Content Management or Base API: Loaders

Test my translations

→ Best Practices: Testing

Deploy to production

→ Best Practices: Production

📖 Reading Order

For Beginners

  1. Getting Started Guide – Learn by building
  2. Examples – See more use cases
  3. Best Practices – Level up your implementation

For Advanced Users

  1. Architecture Overview – Understand the system
  2. Base API Documentation – Deep dive into APIs
  3. Parsers – Custom message formats

For Troubleshooting

  1. Troubleshooting Guide – Find your issue
  2. FAQ – Common questions
  3. GitHub Issues – Get help

🤝 Contributing

Interested in contributing to sveltekit-i18n?

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

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