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

npm i svintl -D

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

<script lang="ts">
  import { dict, locale } from '$lib/intl'

  // bind $locale to a dropdown or whatever
</script>

<h1>{$dict.example.hello}</h1>

---

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.

native: English
example:
  hello: "Hello world"

<h1>{$dict.example.hello}</h1>

Values can be specified as JavaScript functions using the following syntax:

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

This looks weird, suggestions are welcome.

Functions can accept arguments:

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

<h1>You have {$dict.example.hello(count)}</h1>

The translation prompt provides clear guidance on using functions across locales to implement phrases with locale-specific rules.

Pluralization

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

items:
  count:
    - one: item
      other: items

product:
  count:
    - one: product
      other: products

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

# 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

<p>You have {$dict.items.count(itemCount)}</p>

Mounts

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.

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

<script lang="ts">
  import { dict as mainDict } from '$lib/intl'
  import { dict as adminDict } from '$lib/intl/admin'
</script>

<div>{$mainDict.foo}</div>
<div>{$adminDict.bar}</div>

Context

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

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

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

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 <lang>, 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.

npx intl

Print help.

npx intl hola

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

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.

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

Creates a new translation entry with optional context.

npx intl mount <mount> <dir>

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

npx intl unmount <mount>

Remove a mount from context.yaml but keep the partition files on disk. The mount can be re-added later using the mount command.

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.

npx intl const example.hello "Hello"

Sets the same value in all dictionaries without translation.

npx intl move example.hello example.greeting.welcome

Moves a translation entry.

npx intl remove example.hello

Removes a translation entry.

npx intl destroy es

Deletes a locale dictionary.

npx intl sync en
npx intl sync en example.hello # sync specific key

Syncs (re-translates) all locales using the source locale dictionary.

npx intl context "Describe shared project background"
npx intl context --clear

Sets or clears project-wide translation guidance stored in context.yaml.

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.