Internationalization for Svelte
npm install svintlDeveloper-friendly CLI tool for managing internationalization dictionaries with automatic translation via OpenAI.
- Bulk dictionary manipulation
- Automatic translation via OpenAI
- Generates typed JavaScript modules
``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
---
> Everything below this line is written by AI.
Dictionary format
The dictionary is an object with an arbitrary structure, where strings are located at the leaves.
`yaml
native: English
example:
hello: "Hello world"
``svelte
{$dict.example.hello}
`Values can be specified as JavaScript functions using the following syntax:
`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)}
`The translation prompt provides clear guidance on using functions across locales to implement phrases with locale-specific rules.
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: itemsproduct:
count:
- one: product
other: products
`For locales with complex pluralization rules (like Russian), include all required forms:
`yaml
Russian pluralization
product:
count:
- one: товар # 1, 21, 31, 41...
few: товара # 2-4, 22-24, 32-34...
many: товаров # 0, 5-20, 25-30...
other: товаров # fallback
`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)}
`$3
Mounts allow you to organize translations into separate directories anywhere in your filesystem. Each mount acts as an independent dictionary that can be imported separately.
`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
{$mainDict.foo}
{$adminDict.bar}
`$3
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 fileinputs:
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
`Create a dictionary mount at the specified path with empty dictionaries for all languages in the root directory. Mounts can be addressed with
mount/key key syntax. Example: npx intl set mount/key "value" "context".`bash
npx intl unmount
`Remove a mount from context.yaml but keep the partition files on disk. The mount can be re-added later using the
mount command.`bash
npx intl unit items.count "item"
`Creates pluralized translation entries for all locales using the object-based format. The system automatically generates appropriate plural forms for each locale based on their pluralization rules.
`bash
npx intl const example.hello "Hello"
`Sets the same value in all dictionaries without translation.
`bash
npx intl move example.hello example.greeting.welcome
`Moves a translation entry or a branch.
`bash
npx intl del example.hello
`Deletes a translation entry or a branch.
`bash
npx intl destroy es
`Deletes a locale dictionary.
`bash
npx intl sync en
npx intl sync en example.hello # sync specific key
`Syncs (re-translates) all locales using the source locale dictionary.
`bash
npx intl context "Describe shared project background"
npx intl context --clear
`Sets or clears project-wide translation guidance stored in
context.yaml.`bash
npx intl genders true
npx intl genders false
`Enables or disables grammatical gender guidance for translations. When enabled, phrases that vary by gender should be stored as functions that accept
gender: 'he' | 'she' | 'none'. Use the neutral form when possible; otherwise use a combined form (e.g., бежал(а), должен(на)), and avoid neuter forms for people.Example:
`yaml
run: |
!js
(gender) => gender === "she" ? "бежала" : gender === "he" ? "бежал" : "бежал(а)"
``bash
npx intl build
`Generates JavaScript dictionaries and TypeScript types from YAML files. Creates
built.js and types.ts` files that can be imported in your Svelte application.