@sveltekit-i18n/sv

A Svelte CLI add-on that sets sveltekit-i18n up in a SvelteKit project: the dependencies, the translations, the /kit wiring and, if you want them, typed keys and a demo page.

npx sv add @sveltekit-i18n

It needs SvelteKit 3. It sets sveltekit-i18n up for the first time: in a project that already depends on sveltekit-i18n or @sveltekit-i18n/base, in any version, it stops before writing anything. To move a v2 project to v3, see Upgrading from v2.

Options

sv add asks for each option you do not give.

| Option | Values | Default | What it sets | |--------|--------|---------|--------------| | locales | BCP 47 tags, comma-separated | en | The locales. The first is the one a visitor gets when nothing else decides. | | format | curly, icu, mf2, i18next | curly | The message format. curly installs sveltekit-i18n, which comes with the Curly Message Format. The others install @sveltekit-i18n/base and its parser: @sveltekit-i18n/parser-icu (ICU MessageFormat), parser-mf2 (Unicode MessageFormat 2) or parser-i18next (i18next's syntax). | | routing | cookie, prefix, custom | cookie | Where a request's locale comes from. cookie: the lang cookie, then Accept-Language, and URLs stay as they are. prefix: the path, with /about in the first locale and /cs/about in another. custom: event.locals.lang, which a handle stub in hooks.server leaves for you to fill. | | typegen | yes, no | yes | Types for your keys and payloads, generated by @sveltekit-i18n/typegen. | | extensions | typed-access, html, stores, or none | none | The official extensions to apply, in that order whatever order you give them in. | | demo | yes, no | yes | A demo page at /demo/sveltekit-i18n, with a locale switcher. |

Every option can be given on the command line, which then asks nothing:

npx sv add @sveltekit-i18n="locales:en,cs+format:icu+routing:prefix+typegen:yes+extensions:typed-access,html+demo:yes"

What it changes

The paths below are the default ones of a TypeScript project. A JavaScript project gets .js files, typed with JSDoc. The add-on changes a file that exists already under either extension.

• package.json: the packages of the format, the extensions you chose and, with typegen, @sveltekit-i18n/typegen as a dev dependency. It also adds the #lib and #lib/* entries of imports the project lacks.
• src/lib/translations/<locale>/common.json: a message for each locale.
• src/lib/i18n.ts: the config and its loaders, and handle, load, use and get from defineI18n. All logs and reports go to one logger, console by default, so you replace it in one place.
• src/hooks.server.ts: the handle, run after your own when you have one.
• src/routes/+layout.server.ts and src/routes/+layout.ts: the load of each layout. An existing load is wrapped, so its own data still reaches your pages.
• src/routes/+layout.svelte: use(() => data).
• src/app.html: lang="%lang%" and dir="%dir%" on <html>.
• With routing: prefix: src/lib/locale.ts (the locale helpers) and the locale matcher in src/params.ts. The demo page goes under the optional [[lang=locale]] segment. Your own routes stay where they are; move them under that segment to serve them in every locale.
• With routing: custom: lang in App.Locals in src/app.d.ts.
• With typegen: the plugin in vite.config.ts, and src/i18n-schema.d.ts in .gitignore.
• With demo: the page, and its link in sv's list of demos.

It stops before writing anything when src/lib/i18n.ts exists and does not call defineI18n, and, with routing: prefix, when src/lib/locale.ts exists and does not parse or lacks an export the generated files import, or when it cannot read kit.paths.base as a string literal (Kit's options in vite.config.ts that are not an object literal included): the locale helpers strip the base from every path.

When it cannot merge into a file, because the file does not parse or has a shape the add-on does not handle (a handle or load that may come from an export *, a load declared with let, a layout that declares its props with export let), it leaves that file alone and says what is left to do once it finishes. Running it a second time changes nothing.

Docs

The docs of the library are at sveltekit-i18n.github.io, and the examples show each setup in a full app.

License

MIT