Package detail

typesafe-i18n

ivanhofer108.9kMIT5.26.2

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

i18n, typescript, internationalization, typesafe, l10n, localization, internationalization library, localization library, localization engine, lightweight, svelte, sveltekit, react, react-native, nextjs, expo, angular, vue, nuxtjs, solid, nodejs

readme

:earth_africa: typesafe-i18n

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

GitHub Top Language types included

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

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

:keyboard: Run the setup process and automatically detect the config needed
```
npx typesafe-i18n --setup-auto
```
or manually configure typesafe-i18n by answering a few questions
```
npx typesafe-i18n --setup
```
It didn't work? See here for possible troubleshooting.
:eyes: Take a look at the generated files and it's folder-structure after running npm run typesafe-i18n (or npx typesafe-i18n)
: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.
: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 locales completion

typesafe auto-completion for all available translations

typesafe translation key completion

you will get an error if you forget to pass arguments

typesafe number of arguments

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

typesafe arguments 1 typesafe arguments 2

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

typesafe keys in translations

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

typesafe arguments in translation

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 performance:

the amount of network traffic is kept small\ The translation functions are small. Only the locales that are used are loaded
no unnecessary workload\ Parsing your translation file for variables and formatters will only be performed when you access a translation for the first time. The result of that parsing process will be stored in an optimized object and kept in memory.
fast translations\ Passing variables to the translation function will be fast, because its treated like a simple string concatenation. For formatting values, a single function is called per formatter.

If you use typesafe-i18n you will get a smaller bundle compared to other i18n solutions. But that doesn't mean, we should stop there. There are some possible optimizations planned to decrease the bundle size even further.

FAQs

Dou you still have some questions? Reach out to us via Github Discussions or on Discord.

Calling `LL.key()` renders an empty string

You probably forgot to load the locale first before using it. Calling loadLocaleAsync('en') or loadAllLocales() will fix it.

Installing `typesafe-i18n` fails

Running the npx command with a npm version <7.0.0 will probably fail because it will not include peerDependencies.

You could try installing it locally via:

npm install typesafe-i18n

and then run the setup-command from within the node_modules folder via:

./node_modules/typesafe-i18n/cli/typesafe-i18n.mjs --setup-auto

here is the original issue with some additional information: #142

I added a new translation to my locale file, but TypeScript gives me the Error `Property 'XYZ' does not exist on type 'TranslationFunctions'`

Make sure to run the generator after you make changes to your base translation file. The generator will generate and update the types for you.

I don't use TypeScript, can I also use `typesafe-i18n` inside JavaScript applications?

Yes, you can. See the usage section for instructions. Even if you don't use TypeScript you can still improve from some typesafety features via JSDoc-annotations.

I added a new translation to my locale file, but the generator will not create new types

The generator will only look for changes in your base locale file. Make sure to always update your base locale file first, in order to get the correct auto-generated types. If you want to change your base locale file, make sure to give it the type of BaseTranslation. All other locales should have the type of Translation. E.g. if you set your base locale to italian, you would need to do it like this:

set your base locale to italian (it) in ´.typesafe-i18n.json`:
```
{
   "baseLocale": "it"
}
```

define the type of your base locale as BaseTranslation

// file 'src/i18n/it/index.ts'
import type { BaseTranslation } from '../i18n-types'

const it: BaseTranslation = {
   WELCOME: "Benvenuto!"
}

export default it

define the type of your other locales as Translation

// file 'src/i18n/en/index.ts'
import type { Translation } from '../i18n-types'

const en: Translation = {
   WELCOME: "Welcome!"
}

export default en

The generator keeps overriding my changes I make to the i18n-files

The generator creates some helpful wrappers for you. If you want to write your own wrappers, you can disable the generation of these files by setting the generateOnlyTypes option to true.

Is `typesafe-i18n` supported by `i18n-ally`?

Yes, you can configure i18n-ally like this. There is currently also an open PR that will add official support for typesafe-i18n.

How can I access a translation dynamically?

When you want to dynamically access a translation, you can use the usual JavaScript syntax to access a property via a variable (myObject[myVariable]).

define your translations `ts // i18n/en.ts import type { BaseTranslation } from '../i18n-types'

const en: BaseTranslation = { category: { simple: { title: 'Simple title', description: 'I am a description for the "simple" category', }, advanced: { title: 'Advanced title', description: 'I am a description for the "advanced" category', } } }

export default en


2. use it in your components

```html
<script lang="ts">
   // Component.svelte

   import LL from '$i18n/i18n-svelte'
   import type { Translation } from '$i18n/i18n-types'

   // ! do not type it as `string`
   // by restricting the type, you don't loose the typesafety features
   export let category: keyof Translation['category'] = 'simple'
</script>

<h2>{$LL.category[category].title()}

<p>
   {$LL.category[category].description()}
<p>

How can I have translated validation messages?

Validation libraries like zod, yup, joi etc. usually provide a way to define custom error messages. You can use typesafe-i18n to translate these messages.

But you need to create the validation schema dynamically, after you have initialized the LL object ([]i18nObject](https://github.com/ivanhofer/typesafe-i18n/tree/main/packages/runtime#i18nObject)).

You can do that like this by passing the LL object to a function that returns the validation schema:

import { z } from 'zod'
import type { TranslationFunctions } from './i18n/i18n-types'

export const createLoginSchema = (LL: TranslationFunctions) => z.object({
    email: z.string().min(1, LL.validation.emptyField()).email(LL.validation.invalidEmail()),
    password: z.string().min(1, LL.validation.emptyField()),
})

How do I render a component inside a Translation?

By default typesafe-i18n at this time does not provide such a functionality. Basically you will need to write a function that splits the translated message and renders a component between the parts. You can define your split characters yourself but you would always need to make sure you add them in any translation since typesafe-i18n doesn't provide any typesafety for these characters (yet).

How can I use my base translation as a fallback for other locales?

With the strong typesafety features, you'll know if a locale is missing a translation. But in rare cases you might want to use your base translation as a fallback for other locales.

See the next FAQ entry. The same concept can be applied to prefill your translations with the base translation and then just override the parts that are translated.

You'll loose the some sort of typesafety with that approach since you can't know which parts are translated and which are not. Using the base translation as a fallback is not recommended because your UI will contain two different locales which might confuse your users.

I have two similar locales (only a few translations are different) but I don't want to duplicate my translations

Your locale translation files can be any kind of JavaScript object. So you can make object-transformations inside your translation file. The only restriction is: in the end it has to contain a default export with type Translation. You could do something like this:

create your BaseTranslation

// file 'src/i18n/en/index.ts'
import type { BaseTranslation } from '../i18n-types'

const en: BaseTranslation = {
   WELCOME: "Welcome to XYZ",
   // ... some other translations

   COLOR: "colour"
}

export default en

create your other translation that overrides specific translations

// file 'src/i18n/en-US/index.ts'
import type { Translation } from '../i18n-types'
import en from '../en' // import translations from 'en' locale

const en_US: Translation = {
   ...en as Translation, // use destructuring to copy all translations from your 'en' locale

   COLOR: "color" // override specific translations
}

export default en_US

If you are using nested translations, you should use the provided extendDictionary function that uses just-extend under the hood.

import { extendDictionary } from '../i18n-utils'
import en from '../en' // import translations from 'en' locale

const en_US = extendDictionary(en, {
   labels: {
      color: "color" // override specific translations
   }
})

export default en_US

For certain locales I don't want to output a variable, but due to the strict typing I have to specify it in my translation

The generated types are really strict. It helps you from making unintentional mistakes. If you want to opt-out for certain translations, you can use the any keyword.

create your BaseTranslation with a translation containing a parameter

// file 'src/i18n/en/index.ts'
import type { BaseTranslation } from '../i18n-types'

const en: BaseTranslation = {
   HELLO: "Hi {name}!",
}

export default en

create another locale without that parameter by disabling the strict type checking with as any

// file 'src/i18n/de/index.ts'
import type { Translation } from '../i18n-types'

const de: Translation = {
   HELLO: "Hallo!" as any // we don't want to output the 'name' variable
}

export default de

WARNING! the usage of 'any' can introduce unintentional mistakes in future. It should only be used when really necessary and you know what you are doing.

A better approach would be to create a custom formatter e.g.

create your translation and add a formatter to your variable

// file 'src/i18n/en/index.ts'
import type { BaseTranslation } from '../i18n-types'

const en: BaseTranslation = {
   HELLO: "Hi {name|nameFormatter}!",
}

export default en

// file 'src/i18n/de/index.ts'
import type { Translation } from '../i18n-types'

const de: Translation = {
   HELLO: "Hallo {name|nameFormatter}!"
}

export default de

create the formatter based on the locale

// file 'src/i18n/formatters.ts'
import type { FormattersInitializer } from 'typesafe-i18n'
import type { Locales, Formatters } from './i18n-types'
import { identity, ignore } from 'typesafe-i18n/formatters'

export const initFormatters: FormattersInitializer<Locales, Formatters> = (locale: Locales)    => {

   const nameFormatter =
      locale === 'de'
         // return an empty string for locale 'de'
         ? ignore // same as: () => ''
         // return the unmodified parameter
         : identity // same as: (value) => value

   const formatters: Formatters = {
      nameFormatter: nameFormatter
   }

   return formatters
}

Why does the translation function return a type of `LocalizedString` and not the type `string` itself?

With the help of LocalizedString you could enforce texts in your application to be translated. Lets take an Error message as example:

const showErrorMessage(message: string) => alert(message)

const createUser = (name: string, password: string) => {
   if (name.length === 0) {
      showErrorMessage(LL.user.create.nameNotProvided())
      return
   }

   if (isStrongPassword(password)) {
      showErrorMessage('Password is too weak')
      return
   }

   // ... create user in DB
}

In this example we can pass in any string, so it can also happen that some parts of your application are not translated. To improve your i18n experience a bit we can take advantage of the LocalizedString type:

import type { LocalizedString } from 'typesafe-i18n'

const showErrorMessage(message: LocalizedString) => alert(message)

const createUser = (name: string, password: string) => {
   if (name.length === 0) {
      showErrorMessage(LL.user.create.nameNotProvided())
      return
   }

   if (isStrongPassword(password)) {
      showErrorMessage('Password is too weak') // => ERROR: Argument of type 'string' is not assignable to parameter of type 'LocalizedString'.
      return
   }

   // ... create user in DB
}

With the type LocalizedString you can restrict your functions to only translated strings.

Tests are not running with `Jest`

Unfortunately there are some open issues in the Jest repository regarding modern package export formats so jest doesn't know where to load files from.

You need to manually tell jest where these files should be loaded from, by defining moduleNameMapper inside your jest.config.js:

// jest.config.js
module.exports = {
   moduleNameMapper: {
      "typesafe-i18n/angular": "typesafe-i18n/angular/index.cjs",
      "typesafe-i18n/react": "typesafe-i18n/react/index.cjs",
      "typesafe-i18n/solid": "typesafe-i18n/solid/index.cjs",
      "typesafe-i18n/svelte": "typesafe-i18n/svelte/index.cjs",
      "typesafe-i18n/vue": "typesafe-i18n/vue/index.cjs",
      "typesafe-i18n/formatters": "typesafe-i18n/formatters/index.cjs",
      "typesafe-i18n/detectors": "typesafe-i18n/detectors/index.cjs",
   }
};

here is the original issue with some additional information: #140

With Node.JS the `Intl` package does not work with locales other than 'en'

Node.JS, by default, does not come with the full intl support. To reduce the size of the node installment it will only include 'en' as locale. You would need to add it yourself. The easiest way is to install the intl package

> npm install intl

and then add following lines on top of your src/i18n/formatters.ts file:

const intl = require('intl')
intl.__disableRegExpRestore()
globalThis.Intl.DateTimeFormat = intl.DateTimeFormat

Then you should be able to use formatters from the Intl namespace with all locales.

Note: this is an older approach to the problem. You should not need this when using Node.js version > 16.

"Cannot find module" in yarn monorepo setup

Yarn uses a strange way to install dependencies in a monorepo setup. The issue lays in the "hoisting" of packages (see this issue). Therefore it might be that the typesafe-i18n dependencies cannot be found.

Changing the workspace config in package.json will fix the issue:

-  "workspaces": [
-    "apps/*",
-    "packages/*"
-  ],
+  "workspaces": {
+    "packages": [
+      "apps/*",
+      "packages/*"
+    ],
+    "nohoist": [
+      "**/typesafe-i18n",
+      "**/typesafe-i18n/**"
+    ]
+  },

changelog

CHANGELOG.md

Version 5

5.26.1 (2023-08-14)

Fix:

recompute LL object after calling setLocale in adapter-react #721

5.26.0 (2023-08-01)

Feat:

improved plural rules support for polnish #672

5.25.1 (2023-07-20)

Fix:

replace lodash.merge with just-extend"

5.25.0 (2023-07-18)

Feat:

add support for TypeScript >5.1

5.24.4 (2023-07-10)

Fix:

avoid recomputing react context #684

5.24.3 (2023-03-26)

Fix:

correctly inject typesafe-i18n script in package.json if block contains brackets #631

5.24.2 (2023-03-02)

Fix:

extendDictionary functionality to not mutate original object #618

5.24.1 (2023-02-13)

Fix:

make exporter work on windows again #600
indentation of generated namespace function

5.24.0 (2023-02-05)

Feature:

add deno adapter

5.23.2 (2023-02-05)

Fix:

utils package

5.23.1 (2023-02-05)

Fix:

add missing package.exports

5.23.0 (2023-02-04)

Feature:

add extendDictionary functionality

5.22.0 (2023-02-04)

Feature:

use satisfies operator where possible

5.21.0 (2023-01-30)

Feature:

run runAfterGenerator hook when using the importer #579

5.20.0 (2023-01-18)

Feature:

expose experimentalParseMessage and experimentalSerializeMessage functionality from 'typesafe-i18n/parser'

5.19.1 (2023-01-17)

Fix:

actually publish config folder

5.19.0 (2023-01-17)

Feature:

expose getConfig and getLocaleInformation functionality from 'typesafe-i18n/config'

5.18.0 (2022-12-22)

Feature:

allow to have strings with a comma inside switch-case statements #548

5.17.2 (2022-12-18)

Bugfix:

react JSDoc output

5.17.1 (2022-11-28)

Fix:

type-import for vue adapter

5.17.0 (2022-11-25)

Feature:

better esm support

Fix:

fix async namespace imports for esm output #514
add types to package.json exports #514

5.16.3 (2022-11-08)

Fix:

types for TypeScript moduleResolution 'Node16'

5.16.2 (2022-11-02)

Fix:

generator esm imports

5.16.1 (2022-11-01)

Fix:

generating types for namespaces when outputFormat is set to JavaScript #491

5.16.0 (2022-11-01)

Feature:

make generator faster by improving the speed of the TypeScript compilation process

5.15.0 (2022-10-19)

Feature:

use type predicates for isLocale and isNamespace utility functions #475 Fix:
add ReturnTypes to generated functions to prevent TypeScript performance issues

5.14.0 (2022-09-29)

Feature:

mask original text in Translations entries to not show up in search result while keeping the same hover behavior #453

5.13.1 (2022-09-26)

Fix:

make accept-language-header detector case insensitive #451

5.13.0 (2022-09-14)

Feature:

add isLocale and isNamespace utility functions

5.12.0 (2022-08-17)

Feature:

don't require optional params in translations

5.11.0 (2022-07-28)

Feature:

make generator faster by improving the speed of the TypeScript compilation process

5.10.1 (2022-07-28)

Fix:

link correct types for React adapter

5.10.0 (2022-07-25)

Feature:

break out translation imports into it's own functions #384

5.9.1 (2022-07-25)

Fix:

exported type definitions

5.9.0 (2022-07-24)

5.8.1 (2022-07-24)

internal package modifications

5.8.0 (2022-07-23)

Feature:

auto-setup vue adapter for Nuxt.js applications

5.7.0 (2022-07-16)

Feature:

allow to set multiple adapters #375

5.6.0 (2022-07-05)

Feature:

detect locale from request's hostname

5.5.2 (2022-06-05)

5.5.1 (2022-06-01)

Fix:

bundle 'svelte/store' together with cjs output

5.5.0 (2022-05-29)

replace watchlist with chokidar #314

5.4.3 (2022-05-15)

Fix:

update children types for Solid adapter

5.4.2 (2022-04-29)

Bugfix:

buffer overflow on windows when using namespaces
also trigger generator initially when starting watcher

5.4.1 (2022-04-28)

Fix:

documentation

5.4.0 (2022-04-18)

replace chokidar with watchlist

5.3.6 (2022-04-12)

Fix:

update state with batch inside solid adapter

5.3.5 (2022-04-10)

Fix:

avoid recomputing SolidJS children #267

5.3.4 (2022-04-09)

Fix:

make generated types compatible with 'strictNullChecks: false'
use React.ReactNode instead of React.ReactElement

5.3.3 (2022-04-08)

Fix:

add children to the type definitions of the react component #263

5.3.2 (2022-04-05)

5.3.1 (2022-04-05)

Fix:

improve loading locale and namespace in parallel

5.3.0 (2022-04-04)

Feature:

allow loading locale and namespace in parallel

Fix:

remove unnecessary comma on JSDoc type definitions

5.2.3 (2022-04-01)

Bugfix:

generation of hints when text contains comment-end-marker

5.2.2 (2022-03-28)

Fix:

add reactivity to solid adapter

5.2.1 (2022-03-27)

Fix:

for generating wrong destructuring code for react adapter

5.2.0 (2022-03-27)

Feature:

add solid adapter #193

5.1.2 (2022-03-26)

Fix:

merge definitions correctly if argument and switch-case get used in the same sentence

5.1.1 (2022-03-26)

Bugfix:

don't show TypeScript related Error message when using JSDoc syntax

5.1.0 (2022-03-26)

Fix:

load all locales before initialization of node adapter

Breaking: (will be auto-fixed by running the generator again)

rename the adapter exports

5.0.1 (2022-03-23)

Fix:

hint in setup prompts should mention .mjs instead of .js

5.0.0 (2022-03-23)

Please visit the release post for more information.

Feature:

add typesafeI18nString and typesafeI18nObject functionality #88

BREAKING:

remove functionality to run the generator via a rollup plugin
remove functionality to run the generator via a webpack plugin

Version 4

4.5.0 (2022-03-21)

Feature:

expose the list of available namespaces in i18n-util.ts

4.4.2 (2022-03-12)

Bugfix:

fix importer generating .mjs imports

4.4.1 (2022-03-11)

Bugfix:

fix exporter

4.4.0 (2022-03-11)

Bugfix:

fix generation of types when using the importer feature

4.3.6 (2022-03-11)

Fix:

show error message if BaseTranslation gets not imported from the generated i18n-types file

4.3.5 (2022-03-04)

Fix:

allow to load only namespaces #189

4.3.4 (2022-03-02)

Fix:

possible timeout fix for runAfterGenerator hook #185

4.3.3 (2022-03-02)

Fix:

mock Request type from express for detectors

4.3.2 (2022-03-01)

4.3.1 (2022-03-01)

Fix:

refactor RequiredParams to not use // @ts-ignore comments

4.3.0 (2022-02-26)

Feature:

use generic RequiredParams type instead of creating it for each params-permutation

4.2.2 (2022-02-23)

Fix:

add missing await on writes of new files

4.2.1 (2022-02-23)

Fix:

remove double slash ('//') from generator logs

4.2.0 (2022-02-22)

Feature:

provide a runAfterGenerator hook #185

4.1.5 (2022-02-17)

4.1.4 (2022-02-17)

Fix:

remove sourcemaps from generated bundle #179

4.1.3 (2022-02-16)

Bugfix:

fix importer creating incorrect translations

4.1.2 (2022-02-15)

Bugfix:

generate valid types for uncommon identifiers #177

4.1.1 (2022-02-11)

Bugfix:

translation breaks with key called name name #170

4.1.0 (2022-02-11)

Feature:

add namespaces support for importer and exporter

4.0.0 (2022-02-07)

Please visit the release post for more information.

Feature:

add 'namespaces' functionality #113

BREAKING:

if you have a index-file in a subfolder of your translation files, it will be treated as a namespace

Version 3

3.1.3 (2022-02-07)

Bugfix:

fix react adapter

3.1.2 (2022-02-04)

3.1.1 (2022-02-01)

Fix:

missing index.d.ts in importer #167

3.1.0 (2022-02-01)

Feature:

allow iterating over arrays defined in the dictionary
render an empty string, if key is not valid

3.0.0 (2022-01-29)

Please visit the release post for more information.

BREAKING:

locales have to be loaded in a separate step
remove loadLocalesAsync option from generator
formatters have to be initialized synchronously

closes:

#159
#64

Version 2

2.60.2 (2022-01-28)

Fix:

revert changes made to fallbackProxy #157

2.60.1 (2022-01-22)

Feature:

add functionality to loop over arrays #152

2.59.0 (2022-01-18)

Feature:

add support for JSON files #151

2.58.0 (2022-01-09)

Feature: add better support for monorepos #149

2.57.7 (2022-01-09)

add troubleshoot section for jest issues #140

2.57.6 (2022-01-09)

add troubleshoot section for installing issues #142

2.57.5 (2022-01-02)

show sponsorship message after running the setup-process

2.57.4 (2021-12-28)

2.57.3 (2021-12-28)

2.57.2 (2021-12-28)

Fix:

rename Vue.js exports

2.57.1 (2021-12-27)

Bugfix:

fix CLI script

2.57.0 (2021-12-27)

Feature:

add vue adapter (for vue@3) #121

2.56.0 (2021-12-14)

Feature:

support pnpm as package manager when running the setup-cli #138

2.55.1 (2021-12-06)

Fix:

fix type definition of TranslationFunction for Typescript > 4.5.x [#136][https://github.com/ivanhofer/typesafe-i18n/issues/136)

2.55.0 (2021-12-05)

Feature:

add switch-case support #135

2.54.3 (2021-11-27)

Bugfix:

fix Proxy-access #133

2.54.2 (2021-11-26)

Bugfix:

fix Proxy-access for CJS projects #131

2.54.0 (2021-11-25)

decrease bundle size by a few bytes by removing Angular proxy wrapping on general Proxy instances

2.53.2 (2021-11-24)

Fix:

BaseTranslation type for TypeScript version < 4.4.x #127

2.53.0 (2021-11-24)

Feature:

expose parser function

2.52.2 (2021-11-20)

Fix:

add $schema to json schema definition

2.52.1 (2021-11-19)

Fix:

detect if project uses npm or yarn on CLI setup process

2.52.0 (2021-11-18)

Feature:

add validation of config #112

2.51.1 (2021-11-17)

Feature:

add support for arrays #123

2.50.1 (2021-11-12)

Bugfix:

fix CLI setup

2.50.0 (2021-11-12)

upgrade to node 16

Fix:

default export of generated Locale template file for SvelteKit

2.49.4 (2021-11-07)

Fix:

don't run the generator on CLI setup; show info instead

2.49.3 (2021-11-06)

Bugfix:

add typescript as peer dependency

2.49.2 (2021-11-06)

Bugfix:

include chokidar into bundle

2.49.1 (2021-11-06)

Fix:

SvelteKit workaround for esmModule setup detection

2.49.0 (2021-11-06)

Feature:

setup CLI

2.48.0 (2021-11-01)

Feature:

create typesafe-i18n CLI

2.47.0 (2021-10-31)

Feature:

add option to prevent type updates when importing translations

2.46.8 (2021-10-29)

Bugfix:

wrap translation with correct characters #114

2.46.7 (2021-10-25)

Fix:

expose type LocaleMapping inside importer and exporter

2.46.6 (2021-10-25)

Bugfix:

fix typescript import inside importer and exporter

2.46.5 (2021-10-24)

Fix:

change everything to relative imports so types are resolved correctly

2.46.4 (2021-10-19)

Bugfix:

fix import path for windows/other and esm/cjs matrix

2.46.3 (2021-10-19)

Bugfix:

wrap imported keys with string #110

2.46.2 (2021-10-19)

Fix:

show warning when trying to import empty locale
expose importer and exporter as esm and cjs module

2.46.1 (2021-10-19)

Bugfix:

fix import path on windows #108

2.46.0 (2021-10-18)

Feature:

add exporter feature [#106](https://github.com/ivanhofer/typesafe-i18n/issues/106

2.45.0 (2021-10-16)

Feature:

reduce size of i18n (L) by removing unnecessary Error message

2.44.3 (2021-10-15)

Fix:

detect changes to base translation when using outputFormat: 'JavaScript' #105

2.44.2 (2021-10-14)

Bugfix:

generate types for importer

2.44.1 (2021-10-14)

Fix:

fix variable declaration of JavaScript locale template to be able to display type errors

2.44.0 (2021-10-14)

Feature:

export generator as esm module to make it compatible with SvelteKit in JavaScript mode

2.43.1 (2021-10-14)

Fix:

actually include importer in npm package

2.43.0 (2021-10-12)

Feature:

add importer feature [#69](https://github.com/ivanhofer/typesafe-i18n/issues/69

2.42.0 (2021-10-02)

Breaking:

get rid of locales as generator-config

2.41.0 (2021-10-02)

Feature:

add support for optional parameters [#86](https://github.com/ivanhofer/typesafe-i18n/issues/86

2.40.2 (2021-09-26)

show link to config-README on first start of the generator

2.40.1 (2021-09-22)

2.40.0 (2021-09-22)

Feature:

add angular adapter
add full esm support for adapters

2.39.1 (2021-09-15)

Bugfix:

fix import folders when using esm support

2.39.0 (2021-09-15)

Feature:

add full esm support #80

2.38.0 (2021-09-14)

Feature:

throw an Error when generator detects wrong input syntax when running with --no-watch option

2.37.4 (2021-08-26)

Bugfix:

correctly detect changes in files imported by [baseLocale]/index.ts #76

2.37.3 (2021-08-25)

Bugfix:

allow to generate base files if base locale is not present yet

2.37.2 (2021-08-25)

Fix:

import path of types for time formatter

2.37.1 (2021-08-25)

Fix:

generate unique argument types for Formatters type #75

2.37.0 (2021-08-24)

Feature:

allow to import files to the base locale file from outside of the base locale folder location

2.36.1 (2021-08-21)

Fix:

mark chokidar as dev dependency #73

2.36.0 (2021-07-27)

Fix:

fix all 'esm' and 'cjs' imports to include file ending

2.35.3 (2021-07-26)

Fix:

export files from 'cjs' folder as .cjs files

2.35.2 (2021-07-26)

Fix:

export files from 'esm' folder as .mjs files

2.35.1 (2021-07-19)

Bugfix:

remove browser property from package.json to support older Angular versions

2.35.0 (2021-07-19)

Feature:

add option to generate type-safe JavaScript code trough JSDoc annotations

Readme:

add polyfill info

2.34.0 (2021-07-15)

Feature:

add support for Angular's Proxy implementation

2.33.0 (2021-07-09)

Feature:

add LocalizedString to known types

2.32.3 (2021-07-07)

2.32.2 (2021-07-07)

2.32.1 (2021-07-07)

Bugfix:

fix esm output for react adapter

2.32.0 (2021-07-01)

Fix:

make formatters tree-shakeable
make detectors tree-shakeable

2.31.0 (2021-06-30)

Feature:

output formatters as cjs and esm module

2.30.1 (2021-06-28)

Fix:

show translations on first render for sync react adapter

2.30.0 (2021-06-25)

Feature:

output svelte adapter as cjs and esm module

Fix:

fix cjs and esm import mappings

2.29.0 (2021-06-25)

Feature:

output react adapter as cjs and esm module

2.28.0 (2021-06-25)

Feature:

add --no-watch option to generator node process

2.27.0 (2021-06-18)

Feature:

make TranslationFunctions return a LocalizedString
add banner option to make it possible to disable linting not just for ESLint

2.26.3 (2021-06-07)

Fix:

fix react adapter #49

2.26.2 (2021-06-07)

Fix:

fix wrong types for react and svelte adapters

2.26.1 (2021-06-07)

Fix:

temporary fix for wrong tsc compilation for react and svelte adapters
correctly set formatter path for react adapter

2.26.0 (2021-06-07)

Feature:

add support for nested translation keys
show colorized error-output in console

Fix:

don't generate types when validation failed

Breaking:

translation keys can't contain the '.' character

Other:

don't generate type TranslationKeys anymore

2.25.0 (2021-05-27)

rename watcher to generator

2.24.1 (2021-05-25)

Fix:

inlude detectors files in npm package

2.24.0 (2021-05-25)

Feature:

add locale-detection feature

2.23.2 (2021-05-19)

Fix:

use correct file extension when generating react context

2.23.1 (2021-05-19)

Fix:

fix path for generating schema file

2.23.0 (2021-05-19)

better type-definitions for formatter functions

2.22.0 (2021-05-16)

Feature:

add generateOnlyTypes option
add identity formatter
add ignore formatter

Readme:

create FAQ section

Fix:

wrap types of Formatters in a string to be able to use any kind of formatter name

2.21.1 (2021-05-15)

Fix:

mark chokidar as peer dependency

2.21.0 (2021-05-15)

Fix:

explicitly type parameter locale in initFormatters function

2.20.1 (2021-05-13)

Fix:

use path with implicit version for "$schema" in ./typesafe-i18n.json because redirects are not valid for json schemas

2.20.0 (2021-05-13)

Feature:

add json-schema for ./typesafe-i18n.json config file

Examples:

update dependencies

2.19.1 (2021-05-11)

update dependencies

Bugfix:

better types for TranslationFunctions

2.19.0 (2021-05-07)

Fix:

remove .toString() functionality #27

2.18.0 (2021-04-30)

Feature:

add support for plural rule {{zero|one|other}}

Fix:

detect 0 and '0' always as 'zero' instead of 'other'

2.17.4 (2021-04-27)

Examples:

update to latest typesafe-i18n version

2.17.3 (2021-04-27)

Fix:

mark node script as node executable

2.17.2 (2021-04-26)

Examples:

update to latest typesafe-i18n version

2.17.1 (2021-04-26)

Fix:

run watcher via bin-field in package.json #30

2.17.0 (2021-04-26)

Feature:

add unix support for watcher #29

2.16.1 (2021-04-23)

add CHANGELOG file

Fix:

add deprecation message for .toString() functionality #27

2.16.0 (2021-04-17)

Features:

add webpack plugin to run watcher in development mode

Bugfix:

log watcher-options on startup

2.15.5 (2021-04-13)

Readme:

better describe watcher node-process as fallback for users without supported bundlers

2.15.4 (2021-04-09)

Examples:

update to latest typesafe-i18n version

2.15.3 (2021-04-09)

Fix:

remove a unecessary semicolumn from generated output

2.15.2 (2021-04-09)

update dependencies

2.15.1 (2021-04-02)

upload generated browser bundles as GitHub Action artifact

2.15.0 (2021-04-02)

Feature:

allow to include only selected locales into generated bundle using the rollup-plugin

Fix:

use baseLocale variable as fallback instead of plain string representation inside i18n-util.ts

Readme:

better describe locales option from production bundles

2.14.2 (2021-03-26)

Bugfix:

correctly type initI18nString inside i18n-util.ts

2.14.1 (2021-03-24)

Readme:

describe toString functionality using i18nObject (LL)

2.14.0 (2021-03-24)

Feature;

add toString functionality to i18nObject (LL)

2.13.2 (2021-03-23)

Readme:

update size information

2.13.1 (2021-03-23)

Readme:

fix intendation

2.13.0 (2021-03-23)

Feature:

refactor typesafe-i18n react-component

Security:

update dependencies

2.12.2 (2021-03-19)

Examples:

fix intendation and syntax-highlighting in react README

2.12.1 (2021-03-19)

Readme:

better describe rollup-plugin-typesafe-i18n

Examples:

describe how to use with JavaScript in react README

2.12.0 (2021-03-17)

Feature:

rewrite react adapter using a component instead of hook

2.11.1 (2021-03-17)

Fix:

use wattcher or optimizer rollup plugin depending on rollup environment

2.11.0 (2021-03-17)

Feature:

add react JavaScript adapter

2.10.3 (2021-03-17)

Fix:

generate async i18nString wrapper inside i18n-utils.ts

2.10.2 (2021-03-16)

Examples:

fix intendation in react README

2.10.1 (2021-03-16)

Examples:

add react example

2.10.0 (2021-03-16)

Feature:

add react TypeScript adapter

2.9.2 (2021-03-14)

Readme:

improve screenshots by cropping VS Code frame

2.9.1 (2021-03-14)

Readme:

highlight possible improvements

2.9.0 (2021-03-14)

Feature:

remove argument-types inside translations for production-bundle #13

Examples:

fix labels in svelte example

2.8.3 (2021-03-14)

Examples:

update to latest typesafe-i18n version

2.8.2 (2021-03-14)

Fix:

import svelte adapter from correct file

2.8.1 (2021-03-14)

Fix:

export svelte JavaScript adapter

2.8.0 (2021-03-14)

Feature:

generate async formatters initializer

Fix:

rename exported functions

2.7.1 (2021-03-10)

Readme:

decrease gif file size

2.7.0 (2021-03-08)

Fix:

reduce bundle size by inlining functions from typesafe-utils

2.6.11 (2021-03-06)

Readme:

fix formatter example

2.6.10 (2021-03-05)

Readme:

add status badges

2.6.9 (2021-03-03)

Readme:

highlight advantages
add table of contents
add performance section

2.6.8 (2021-03-03)

Readme:

improvements

2.6.7 (2021-03-01)

Readme:

improvements

2.6.6 (2021-03-01)

Readme:

increase font size of images

2.6.5 (2021-03-01)

Fix:

export svelte store from adapters subpath

2.6.4 (2021-02-28)

Readme:

increase font size of images

2.6.3 (2021-02-28)

Readme:

add gif demonstrating typesafety

2.6.2 (2021-02-28)

Readme:

link images to correct raw file

2.6.1 (2021-02-28)

Readme:

add images demonstrating typesafety

2.6.0 (2021-02-28)

Feature:

allow first part to be plural part when using keyed arguments

2.5.0 (2021-02-28)

Feature:

allow translations with only plural part

2.4.1 (2021-02-24)

Readme:

specify minimum Node.js version

2.4.0 (2021-02-24)

Examples:

add browser example
describe how to use with JavaScript in svelte README

2.3.0 (2021-02-23)

Feature:

export svelte JavaScript store

Readme:

improvements

2.2.5 (2021-02-23)

Fix:

add export maps for svelte adapter

Examples:

add Node.js readme

2.2.4 (2021-02-22)

Examples:

add Node.js example

2.2.3 (2021-02-22)

Feature:

export base locale in i18n-utils.ts

Fix:

improve Node.js adapter

2.2.2 (2021-02-22)

Examples:

update svelte-Example

2.2.1 (2021-02-22)

Examples:

move svelte documentation to svelte example

2.2.0 (2021-02-22)

Feature:

use base locale as fallback if wrong locale was passed during initialization

2.1.0 (2021-02-19)

Feature:

add Node.js adapter
add possibility to define different adapters
allow to rename adapter file name

2.0.5 (2021-02-19)

Examples:

add readme for svelte example

2.0.4 (2021-02-17)

Examples:

add svelte example

2.0.3 (2021-02-17)

Bugfix:

dont throw Error when setLocale is called before init in svelte-adapter

2.0.2 (2021-02-16)

Bugfix:

correctly set current selected locale in svelte store
add possibility to output svelte as synchronous store

2.0.1 (2021-02-16)

Bugfix:

fix synchronous output of i18n-utils.ts

2.0.0 (2021-02-16)

initial release of project under typesafe-i18n name

Package detail

readme

:earth_africa: typesafe-i18n

Advantages

Interactive Live Demo

Works with

Table of Contents

Get started

manual installation

changelog

migrations

Long-term goals

Contributions

Usage

Other frameworks

Custom usage

Browser Support

Typesafety

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

Integration with other services

Sizes

Performance

Sponsors

FAQs

Calling LL.key() renders an empty string

Installing typesafe-i18n fails

I added a new translation to my locale file, but TypeScript gives me the Error Property 'XYZ' does not exist on type 'TranslationFunctions'

I don't use TypeScript, can I also use typesafe-i18n inside JavaScript applications?

I added a new translation to my locale file, but the generator will not create new types

The generator keeps overriding my changes I make to the i18n-files

Is typesafe-i18n supported by i18n-ally?

How can I access a translation dynamically?

How can I have translated validation messages?

How do I render a component inside a Translation?

How can I use my base translation as a fallback for other locales?

I have two similar locales (only a few translations are different) but I don't want to duplicate my translations

For certain locales I don't want to output a variable, but due to the strict typing I have to specify it in my translation

Why does the translation function return a type of LocalizedString and not the type string itself?

Tests are not running with Jest

With Node.JS the Intl package does not work with locales other than 'en'

"Cannot find module" in yarn monorepo setup

changelog

CHANGELOG.md

Version 5

5.26.1 (2023-08-14)

5.26.0 (2023-08-01)

5.25.1 (2023-07-20)

5.25.0 (2023-07-18)

5.24.4 (2023-07-10)

5.24.3 (2023-03-26)

5.24.2 (2023-03-02)

5.24.1 (2023-02-13)

5.24.0 (2023-02-05)

5.23.2 (2023-02-05)

5.23.1 (2023-02-05)

5.23.0 (2023-02-04)

5.22.0 (2023-02-04)

5.21.0 (2023-01-30)

5.20.0 (2023-01-18)

5.19.1 (2023-01-17)

5.19.0 (2023-01-17)

5.18.0 (2022-12-22)

5.17.2 (2022-12-18)

5.17.1 (2022-11-28)

5.17.0 (2022-11-25)

5.16.3 (2022-11-08)

5.16.2 (2022-11-02)

5.16.1 (2022-11-01)

5.16.0 (2022-11-01)

5.15.0 (2022-10-19)

5.14.0 (2022-09-29)

5.13.1 (2022-09-26)

5.13.0 (2022-09-14)

5.12.0 (2022-08-17)

5.11.0 (2022-07-28)

Calling `LL.key()` renders an empty string

Installing `typesafe-i18n` fails

I added a new translation to my locale file, but TypeScript gives me the Error `Property 'XYZ' does not exist on type 'TranslationFunctions'`

I don't use TypeScript, can I also use `typesafe-i18n` inside JavaScript applications?

Is `typesafe-i18n` supported by `i18n-ally`?

Why does the translation function return a type of `LocalizedString` and not the type `string` itself?

Tests are not running with `Jest`

With Node.JS the `Intl` package does not work with locales other than 'en'