typesafe-i18n: type-checked translations for TypeScript and JavaScript projects

The mistake typesafe-i18n is built to prevent

Most i18n libraries treat translations as data. You call a function with a string key and get a string back, and nothing checks that the key exists or that the values you interpolate match the placeholders in the translation. A typo in a key surfaces in production as a raw key name on screen. A renamed placeholder surfaces as a blank or a literal brace. typesafe-i18n moves that check to the compiler by generating TypeScript types from your base locale. The README describes the library as a fully type-safe and lightweight internationalization library for all your TypeScript and JavaScript projects, and the type safety is the whole pitch. It is aimed at application developers who already use TypeScript, or who use plain JavaScript and want the generator to emit JSDoc comments that give editors the same hints. The repository topics list Angular, React, Solid, Svelte, Vue and Node.js, and the package exports separate entry points for angular, detectors, exporter, formatters, importer and parser, so the library is meant to sit inside a frontend framework or a backend service rather than replace one.

How the generator and the runtime split the work

The repository is a pnpm workspace with a packages directory, and the published package exposes several subpath exports. The runtime is the part your application imports at run time. The generator is a separate step that reads your base translation file, writes type definitions and locale files into a generated folder, and is what makes the keys typed. The README links to a folder structure section in the generator package, which is where the generated layout is documented. The runtime itself is small: the README states roughly 1kb, and the project tracks that with a size-limit configuration at the repository root. Beyond plain key lookup, the runtime supports plural rules, switch-case statements for output that depends on an argument such as gender, and formatters for locale-dependent dates and numbers. Locale detection for browser and server environments lives in the detectors package, and the importer and exporter packages move translations to and from files or services. There are no external dependencies, according to the README. The architecture is therefore a compile-time generator plus a dependency-free runtime, and the boundary between them is the generated folder.

Installing typesafe-i18n and running the generator once

The README points to a Get started section for adding the library to a project, and the package is published on npm under the name typesafe-i18n. Install it as a dev dependency, because the generator is the part you run during development and the runtime is imported by your source. The exact install command is not spelled out in the README beyond the npm package name, so the form below is the standard npm invocation for that package.

First real use: a base locale and a typed call

A first use means creating a base translation file and letting the generator produce the typed wrappers. The README links to a syntax page in the runtime package for the translation function syntax and a dictionary page for structuring translations, but it does not print a full example in the section shown here, so the shape below follows the documented concepts: a base locale file, a generated folder, and a call that passes arguments for placeholders. Treat the file paths as the ones the generator creates, not as arbitrary choices.

The generated folder is the real cost

Because types are derived from the base locale, the generated folder has to be rebuilt whenever that file changes. A new key added to the base locale is invisible to the runtime until the generator runs again, and a key removed from the base locale leaves a stale generated entry until the next run. In a team, that means deciding whether generated output is committed to the repository or produced during the build. Committing it makes code review show the diff of every generated type, which is noisy but keeps the build free of a generation step. Generating it during the build keeps the repository clean but means a missing generation step fails the build rather than the editor. The README does not state a preference, and it does not document rollback of generated output. This is a real trade-off, not a defect: the type safety is purchased with a build step that other i18n libraries do not require. The release history shows 5.27.0 and 5.27.1 published on 2026-02-11, and the last push to the repository was on 2026-03-22, so the project is not dormant, but the generator workflow is the part most likely to cause friction in an existing codebase.

Where typesafe-i18n is the wrong choice

If your translations are owned by a translation management service and downloaded at build time, the generator has no stable base locale to read, and its type guarantees depend on that file being the source of truth. If you need locale data for plural rules or date and number formats across a long tail of languages, the README does not claim to ship CLDR data; it documents plural rules and formatters as features, but the README does not enumerate the supported locales, so verify coverage for the languages you actually ship before adopting. If your team is not using TypeScript and does not want JSDoc-driven editor hints, the main advantage disappears and you are paying for a generator to get what a plain dictionary would give you. And if your build pipeline cannot tolerate a code generation step, a runtime-only library with a lookup function and a lint rule for key existence is a smaller change.

How it compares with i18next

i18next is the most common alternative and appears in the related searches for this project. The difference is where the safety comes from. i18next loads dictionaries at run time, supports a plugin ecosystem for backends, detectors and post-processing, and leaves key correctness to tooling and tests around it. typesafe-i18n inverts that: the generator is not optional, and correctness is enforced by the TypeScript compiler against a base locale. i18next is the better fit when you need runtime language switching with remote resources, a large plugin surface, or a framework integration that already assumes it. typesafe-i18n is the better fit when your translations are files in the repository, you write TypeScript, and you would rather have the compiler reject a bad key than add a test that checks for it. The trade is ecosystem breadth for compile-time guarantees.

Licence, maintenance and upgrade cost

The package is published under the MIT licence, which permits commercial use and modification provided the copyright notice and licence text are retained. That is a permissive licence with no copyleft obligation, but it is not legal advice; check how your organisation handles third-party notices. Maintenance is visible in the repository rather than in a support contract: the last push was on 2026-03-22, and the most recent releases are 5.27.0 and 5.27.1 from 2026-02-11. There is a CHANGELOG.md at the repository root and a release-please configuration, which suggests releases are cut from conventional commits. Upgrade cost is dominated by the generated folder: a version bump can change the generated output, so the diff after upgrading is the thing to read. The runtime is small and dependency-free, so the risk of a transitive dependency breaking is low. Budget time for regenerating and reviewing the generated files on each upgrade rather than for API migration.

Editorial conclusion

Adopt typesafe-i18n when you write TypeScript or JavaScript, want missing translation keys and wrong placeholder arguments caught by the compiler, and can accept a generated folder that must be regenerated whenever a base translation changes. Skip it if your translations live in a translation management service that owns the files, or if you need locale data for languages whose plural rules the runtime does not cover and cannot ship a custom rule. Before committing, verify three things in your own checkout: that the generator runs against your existing locale files without losing placeholders, that the generated output is committed or rebuilt in CI, and that the runtime size stays inside your budget once formatters and detectors are added.

Frequently asked questions

Official sources

1. codingcommons/typesafe-i18n on GitHub
2. License: MIT
3. Project website
4. README
5. Releases