Parsers

Message parsers for sveltekit-i18n. These parsers handle the interpolation of dynamic values in your translations. While designed for @sveltekit-i18n/base, they can be used with any library – they don't require Svelte or SvelteKit.

Available Parsers

@sveltekit-i18n/parser-curly

The Curly Message Format — placeholders, defaults, modifiers and comparisons in double curly braces — resolved by @curly-message/parser, the format's reference implementation.

npm install @sveltekit-i18n/parser-curly

Features:

• Simple placeholder syntax: {{name}}
• Built-in modifiers: number, date, currency, ago
• Conditional rendering: {{count; 1:item; default:items;}}
• Comparison operators: eq, ne, lt, gt, lte, gte
• Custom modifiers support
• Build-time parameter extraction: extractParamsFactory
• One dependency: the format's reference implementation

Example:

{
  "greeting": "Hello, {{name}}!",
  "items": "You have {{count:number;}} {{count; 1:item; default:items;}}.",
  "price": "Price: {{value:currency;}}",
  "updated": "Updated {{date:ago;}}"
}

📖 Full documentation

@sveltekit-i18n/parser-icu

ICU message format parser powered by intl-messageformat.

npm install @sveltekit-i18n/parser-icu

Features:

• Industry-standard ICU message syntax
• Plural rules: {count, plural, one {# item} other {# items}}
• Select format: {gender, select, male {He} female {She} other {They}}
• Number formatting: {price, number, ::currency/USD}
• Date/time formatting: {date, date, ::yyyyMMdd}
• Build-time parameter extraction: extractParamsFactory

Example:

{
  "greeting": "Hello, {name}!",
  "items": "You have {count, plural, =0 {no items} one {# item} other {# items}}.",
  "response": "{gender, select, male {He} female {She} other {They}} will respond shortly."
}

📖 Full documentation

@sveltekit-i18n/parser-mf2

Unicode MessageFormat 2 parser powered by messageformat, the format's reference implementation.

npm install @sveltekit-i18n/parser-mf2

Features:

• The Unicode standard's successor to ICU MessageFormat
• Variables and functions: {$count :integer}, {$price :currency currency=USD}
• Declarations: .input {$count :integer}, .local $total = {$price :number}
• Selection with plural categories and exact matches: .match $count / 0 {{None}} / one {{One}} / * {{{$count}}}
• Date, time, currency, percent and unit formatting out of the box
• Build-time parameter extraction: extractParamsFactory

@sveltekit-i18n/parser-i18next

The i18next interpolation and formatting syntax, for translation files that already exist in it — an adapter over i18next itself, so a message renders as it did there.

npm install @sveltekit-i18n/parser-i18next

Features:

• i18next placeholders: {{name}}, {{- html}}, {{user.name}}
• Built-in formats with their argument syntax: {{n, currency(USD)}}, {{d, datetime(dateStyle: long)}}
• Per-call formatParams and custom formats
• i18next's own interpolation options and missingInterpolationHandler
• Build-time parameter extraction: extractParamsFactory
• One dependency: i18next itself, about 44 kB minified

Example:

{
  "greeting": "Hello, {$name}!",
  "items": ".input {$count :integer}\n.match $count\n0 {{You have no items.}}\none {{You have one item.}}\n* {{You have {$count} items.}}",
  "response": ".input {$gender :string}\n.match $gender\nmale {{He will respond shortly.}}\nfemale {{She will respond shortly.}}\n* {{They will respond shortly.}}"
}

📖 Full documentation "greeting": "Hi {{name}}!", "price": "{{amount, currency(USD)}}", "updated": "{{days, relativetime}}", "guests": "{{names, list}}" }

[📖 Full documentation](./parser-i18next/README.md)

## Choosing a Parser

### Use `parser-curly` if:
- You want a small, specified syntax with a conformance set behind it
- You need a lightweight solution
- You prefer simple, readable syntax
- You want to create custom modifiers easily
- Your translation needs are straightforward

### Use `parser-icu` if:
- You need industry-standard ICU message format
- You're migrating from other i18n libraries that use ICU
- You need advanced plural rules for complex languages
- You want built-in number/date/time formatting options
- You're comfortable with ICU syntax

### Use `parser-mf2` if:
- You want the Unicode standard's current message format, MessageFormat 2
- You need selection on several values at once, or a value declared once and formatted in one place
- You want number, date, time, currency, percent and unit formatting stated inside the message
- You want a message format that other tooling, in other languages, reads too
### Use `parser-i18next` if:
- Your translation files are already written for i18next
- You want i18next's own engine rendering them, so nothing changes on the way
- You need its built-in `number`, `currency`, `datetime`, `relativetime` and `list` formats
- A dependency of about 44 kB is a fair price for not rewriting a catalogue

## Using Parsers

### With sveltekit-i18n

The main `sveltekit-i18n` package includes `parser-curly` by default:

```javascript
import { I18n } from 'sveltekit-i18n';

const config = {
  // parser-curly is already included
  loaders: [/* ... */],
};

export const i18n = new I18n(config);

With @sveltekit-i18n/base

Use any parser with the base package:

import { I18n } from '@sveltekit-i18n/base';
import parser from '@sveltekit-i18n/parser-curly';
// or: import parser from '@sveltekit-i18n/parser-icu';
// or: import parser from '@sveltekit-i18n/parser-mf2';
// or: import parser from '@sveltekit-i18n/parser-i18next';

const config = {
  parser: parser({
    // parser-specific options
  }),
  loaders: [/* ... */],
};

export const i18n = new I18n(config);

Creating Custom Parsers

You can create your own parser to support any message syntax you need.

Basic Structure

A parser is a function that returns an object with a parse method. What base guarantees before it calls parse, and what it requires back, is the parser contract; this repository keeps it as a set of checks in contract/ that every shipped parser runs against itself:

const customParser = (config = {}) => ({
  parse: (value, params, locale, key) => {
    // value: translation string from your JSON file
    // params: array of parameters passed to t()
    // locale: current locale (e.g., 'en', 'cs')
    // key: translation key (e.g., 'common.greeting')
    
    // Return interpolated string
    return value;
  },
});

Example: Simple Template Literals

const templateParser = () => ({
  parse: (value, params) => {
    const vars = params[0] || {};
    return value.replace(/\${(\w+)}/g, (_, key) => vars[key] ?? key);
  },
});

// Usage in translations:
// { "greeting": "Hello, ${name}!" }

Example: Mustache-style Syntax

const mustacheParser = () => ({
  parse: (value, params) => {
    const vars = params[0] || {};
    return value.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
  },
});

// Usage in translations:
// { "greeting": "Hello, {{name}}!" }

Example: Advanced with Modifiers

const advancedParser = (config = {}) => ({
  parse: (value, params, locale) => {
    const vars = params[0] || {};
    
    return value.replace(/\{(\w+)(?::(\w+))?\}/g, (match, key, modifier) => {
      const val = vars[key];
      
      if (modifier === 'upper') return String(val).toUpperCase();
      if (modifier === 'lower') return String(val).toLowerCase();
      if (modifier === 'number') return new Intl.NumberFormat(locale).format(val);
      
      return val ?? key;
    });
  },
});

// Usage in translations:
// { "greeting": "Hello, {name:upper}!", "count": "{value:number}" }

Using Your Custom Parser

import { I18n } from '@sveltekit-i18n/base';
import customParser from './custom-parser';

const config = {
  parser: customParser(),
  loaders: [/* ... */],
};

export const i18n = new I18n(config);

Parser Configuration

Each parser accepts its own configuration options. Check the specific parser documentation:

• parser-curly options
• parser-icu options
• parser-mf2 options
• parser-i18next options

Documentation

• 🌐 sveltekit-i18n.github.io – The documentation site, with a live playground
• 📖 Complete Documentation Index – All guides and references
• 🚀 Getting Started – Quick tutorial
• 📚 Best Practices – Production patterns

TypeScript Support

All official parsers include full TypeScript support:

import parser from '@sveltekit-i18n/parser-curly';
import type { Config } from '@sveltekit-i18n/parser-curly';

const config: Config = {
  parser: parser({
    // typed options
  }),
  loaders: [/* ... */],
};

Contributing

For general contribution guidelines, see the Contributing Guide.

For parser-specific contributions and issues, use this repository's issues.

Sponsor

You can support the maintenance of these packages through GitHub Sponsors.

License

MIT