typesafe-i18n

:earth_africa: typesafe-i18n

A fully type-safe and lightweight internationalization library for all your TypeScript and JavaScript projects.

Created by Ivan Hofer (1995-2023)

Advantages

:baby_chick: lightweight (~1kb)
:ok_hand: easy to use syntax
:running: fast and efficient
:safety_vest: prevents you from making mistakes (also in plain JavaScript projects)
:construction_worker: creates boilerplate code for you
:speech_balloon: supports plural rules
:date: allows formatting of values e.g. locale-dependent date or number formats
:left_right_arrow: supports switch-case statements e.g. for gender-specific output
:arrow_down: option for asynchronous loading of locales
:books: supports multiple namespaces
:stopwatch: supports SSR (Server-Side Rendering)
:handshake: can be used for frontend, backend and API projects
:mag: locale-detection for browser and server environments
:arrows_counterclockwise: import and export translations from/to files or services
:no_entry: no external dependencies

Interactive Live Demo

Click here to see an interactive demo of typesafe-i18n showing some key aspects of the type-checking capabilities of this internationalization library.

Works with

Table of Contents

• Get started - how to add typesafe-i18n to your project
• Usage - how to implement different use-cases
• Typesafety - how to get the best typesafety features
• Syntax - how to use the translation functions
• Dictionary - how to structure your translations
• Namespaces - how to optimize loading of your translations
• Formatters - how to format dates and numbers
• Switch-Case - how to output different words depending on an argument
• Locale-detection - how to detect an user's locale
• Utility functions - useful utility functions
• Integrations - how to integrate other i18n services
• Sizes - how much does typesafe-i18n add to your bundle size
• Performance - how efficient is typesafe-i18n implemented
• Sponsors - how to help this project grow
• FAQs - how to get your questions answered

Get started

1. :keyboard: Run the setup process and automatically detect the config needed

   bash复制

   npx typesafe-i18n --setup-auto

   or manually configure typesafe-i18n by answering a few questions

   bash复制

   npx typesafe-i18n --setup

   It didn't work? See here for possible troubleshooting.

2. :eyes: Take a look at the generated files and it's folder-structure after running npm run typesafe-i18n (or npx typesafe-i18n)

3. :open_book: Explore the assets

   typesafe-i18n offers a lot. Just press cmd + F to search on this page or see the table of contents that will link you to more specific subpages with more details.

4. :star: Star this project on GitHub

   Thanks! This helps the project to grow.

Having trouble setting up typesafe-i18n? Reach out to us via Github Discussions or on Discord.

manual installation

npm install typesafe-i18n

changelog

The changelog of this project can be found here

migrations

• to version 5.x.x: see the release post
• to version 4.x.x: see the release post
• to version 3.x.x: see the release post

Long-term goals

Curious about what comes next? See this discussion to learn more about the plans for the future of this project.

Contributions

If you would like to get involved within this project, take a look at this discussion.

Usage

The package can be used inside JavaScript and TypeScript applications. You will get a lot of benefits by running the generator since it will create a few wrappers to provide you with full typesafety.

You can use typesafe-i18n in a variety of project-setups:

• Angular applications
• Node.js apis, backends, scripts, ...
• React / Next.js applications
• Solid.js applications
• Svelte / SvelteKit / Sapper applications
• Vue.js / Nuxt.js applications
• Browser (via CDN) projects
• other frameworks

Other frameworks

All you need is inside the generated file i18n-util.ts. You can use the functions in there to create a small wrapper for your application.

Feel free to open a new discussion if you need a guide for a specific framework.

Custom usage

See here if you want to learn how you can use typesafe-i18n to implement your own specific use-case.

Browser Support

The library should work in all modern browsers. It uses some functionality from the Intl namespace. You can see the list of supported browsers here. If you want to support older browsers that don't include these functions, you would need to include a polyfill like intl-pluralrules.

Typesafety

If you want to get the best typesafety features, you will need to use the generator in order to create types and boilerplate code for you

Here you can see some examples where typesafe-i18n can help you:

typesafe auto-completion for all your defined locales

typesafe auto-completion for all available translations

you will get an error if you forget to pass arguments

you will get an error if you pass the wrong type arguments

you will get an error if you forgot to add a translation in a locale

you will get an error when a translation is missing an argument

The typesafe-i18n package allows us to be 100% typesafe for our translation functions and even the translations for other locales itself. The generator outputs TypeScript definitions based on your base locale.

You will also benefit from full typesafe JavaScript code via JSDoc-annotations.

Integration with other services

typesafe-i18n comes with an API that allows other services to read and update translations. You can connect other services by using the importer and exporter functionality.

There also exists an official plugin for Inlang. It allows you to use typesafe-i18n together with the tooling Inlang provides. You can find it here.

Sizes

The footprint of the typesafe-i18n package is smaller compared to other existing i18n packages. Most of the magic happens in development mode, where the generator creates TypeScript definitions for your translations. This means, you don't have to ship the whole package to your users. The only two parts, that are needed in production are:

• string-parser: detects variables, formatters and plural-rules in your localized strings
• translation function: injects arguments, formats them and finds the correct plural form for the given arguments

These parts are bundled into the core functions. The sizes of the core functionalities are:

• i18nString: 948 bytes gzipped
• i18nObject: 1089 bytes gzipped
• i18n: 1119 bytes gzipped

Apart from that there can be a small overhead depending on which utilities and wrappers you use.

There also exists a useful wrapper for some frameworks:

• typesafe-i18n angular-service: 1230 bytes gzipped
• typesafe-i18n react-context: 1602 bytes gzipped
• typesafe-i18n solid-context: 1403 bytes gzipped
• typesafe-i18n svelte-store: 1342 bytes gzipped
• typesafe-i18n vue-plugin: 1256 bytes gzipped

Performance

The package was optimized for pe