Internationalization for Svelte

Developer-friendly CLI tool for managing internationalization dictionaries with automatic translation via OpenAI.

- Bulk dictionary manipulation
- Automatic translation via OpenAI
- Generates typed JavaScript modules

TL;DR

``bash
npm i svintl -D
`

`bash
npx intl hola # initialize dictionaries in default location
npx intl set example.hello "Hello world" # set a translation
npx intl create es # create a new locale dictionary
npx intl build # generate JavaScript dictionaries
`

`svelte


{$dict.example.hello}

`yaml
native: English
example:
hello: "Hello world"
`

`svelte


{$dict.example.hello}

`yaml
example:
hello: |
!js
() => 'Hello world'
`

> This looks weird, suggestions are welcome.

Functions can accept arguments:

`yaml
example:
hello: |
!js
(count) => ${count || 'No'} item${count === 1 ? '' : 's'}
`

`svelte


You have {$dict.example.hello(count)}

If a phrase contains placeholders like {name} or {itemId}, store it as a !js function with matching parameters.

If a phrase contains placeholders like [names] in square brackets, treat them as array-of-strings parameters and format them with Intl.ListFormat using style: "long" and type: "conjunction". Make the phrase grammatically correct based on the number of items in the array.

Example input:

`bash
npx intl set joined "[names] have joined the {groupName}"
`

Example function output:

`yaml
joined: |
!js
(names, groupName) => {
const list = new Intl.ListFormat("en", { style: "long", type: "conjunction" }).format(names)
return names.length === 1
? ${list} has joined the ${groupName}
: ${list} have joined the ${groupName}
}
`

$3

For pluralized content, use arrays containing objects with named plural forms. This format automatically generates functions that use Intl.PluralRules for proper pluralization:

`yaml
items:
count:
- one: item
other: items

product:
count:
- one: product
other: products
`

For locales with complex pluralization rules (like Russian), include all required forms:

`yaml


Russian pluralization

The array format [{ one: '...', other: '...' }] serves as an indicator for pluralization. The system automatically:

- Detects the array-with-object format
- Generates optimized functions using direct property access
- Eliminates the need for CLDR ordering complexity
- Supports all standard plural categories: zero, one, two, few, many, other

`svelte


You have {$dict.items.count(itemCount)}

`bash
npx intl mount foo ./any/path # creates foo mount with empty dictionaries for all locales
npx intl set foo/bar.baz "Hello mount" # set key in mount 'foo'
`

Mounts are created with the same languages as the root dictionary but start empty (no native key).

Mounts are useful for:

- Organizing large applications by feature/module
- Separate dictionaries for different user roles
- Logical grouping of related translations
- Storing dictionaries in different locations

`svelte


Translation contexts are automatically saved when using the set command with a comment parameter. These contexts enhance translation accuracy when creating new locale dictionaries.

`bash
npx intl set app.welcome "Welcome to our application" "greeting shown on homepage"
`

Contexts are stored in context.yaml alongside your locale files:

`yaml
mounts:
foo: ../../any/path # path relative to this main context file

inputs:
app:
welcome:
input: "Welcome to our application"
context: "greeting shown on homepage"
`

When creating new locales with npx intl create , saved contexts are automatically used to provide more accurate translations by giving the AI translator additional context about how each phrase is used.

CLI

> Translations are powered by OpenAI. Ensure you set the OPENAI_API_KEY in your environment variables.
> .env file is supported.

`bash
npx intl
`

Print help.

`bash
npx intl hola
`

- Create a directory src/lib/intl/ or specified with -p
- Create en-US dictionary
- Generate JavaScript dictionaries and TypeScript types

`bash
npx intl create es
npx intl create en-US
npx intl create pt-BR
`

Creates a new locale dictionary. Locale codes must be valid BCP 47 locale tags. The new dictionary will automatically include a native key with the locale name in that locale.

Dictionary names must be valid BCP 47 locale tags.

`bash
npx intl set example.hello "Hello world"
npx intl set wardrobe.tops "Tops" "Clothing"
`

Creates a new translation entry with optional context.

`bash
npx intl mount