DEV Community: Amer Kočan

How I Made Missing Translations a Compile-Time TypeScript Error

Amer Kočan — Wed, 04 Mar 2026 18:18:44 +0000

Most React i18n libraries catch missing translations at runtime, which means users see broken UI before you do. I wanted TypeScript to catch them before the code ships. Here's how react-scoped-i18n does it.

The standard approach and its failure mode

With key-based libraries like react-i18next, you write something like this:

const { t } = useTranslation();

return <Heading>{t("welcome.message")}</Heading>;

Then in your JSON files:

// en.json
{ "welcome": { "message": "Welcome back!" } }

// es.json
{ "welcome": {} }  // oops - forgot this one

TypeScript has no idea that "welcome.message" is missing from es.json. Your Spanish users get a raw key string rendered in the UI, and it only surfaces when someone actually switches the language. Some libraries offer codegen to produce typed key maps, but that's a build step you have to maintain, and the type safety only covers key existence - not the actual content.

The core idea: translations exist in your components (as code)

Instead of using string keys that point to external files, react-scoped-i18n passes translations as plain object literals directly to the t() function:

const { t } = useI18n();

return <Heading>
    {t({
        en: `Welcome back, ${name}!`,
        es: `¡Bienvenido de nuevo, ${name}!`,
    })}
</Heading>;

This is just a function call. The argument is an object. TypeScript can fully type-check it.

How the type enforcement works

During setup, you declare the languages your app supports:

// i18n/index.ts
import { createI18n } from "react-scoped-i18n";

export const { useI18n, I18nProvider } = createI18n({
    languages: ["en", "es", "sl"],
    defaultLanguage: "en",
});

Internally, createI18n generates a type from that languages array:

type Language = "en" | "es" | "sl";
type Translations = Record<Language, string>;

The t() function expects a Translations object - meaning every key in Language must be present. Leave one out and TypeScript errors immediately:

return <Heading>
    {t({
        en: `Welcome back, ${name}!`,
        es: `¡Bienvenido de nuevo, ${name}!`,
        // TypeScript Error: Property 'sl' is missing in type
        // '{ en: string; es: string; }'
        // but required in type 'Translations'
    })}
</Heading>;

No codegen. No build step. No plugin. The type constraint flows directly from your configuration.

The same guarantee covers pluralization

Pluralization is where most i18n libraries get messy. react-scoped-i18n uses tPlural(), which enforces the same per-language completeness:

const { tPlural } = useI18n();

return <Text>{tPlural(count, {
    en: {
        one: `You have one apple.`,
        many: `You have ${count} apples.`,
    },
    es: {
        one: `Tienes una manzana.`,
        many: `Tienes ${count} manzanas.`,
    },
    sl: {
        one: `Imaš eno jabolko.`,
        two: `Imaš dve jabolki.`,   // Slovenian has a dual form
        many: `Imaš ${count} jabolk.`,
    },
})}</Text>;

At the type level, all categories (negative, zero, one, two, many) are available to every language - you only define what you need. So Slovenian dual forms, Arabic's six-way split, and Polish few all resolve correctly without any hardcoding. Exact number keys and negative are defined as they are used, on top of the spec.

What you give up

This approach works well when developers write and own the translations. If your workflow involves handing off to external translators via Crowdin, Lokalise, or similar platforms, colocated inline translations don't fit that pipeline. For that, you'd want a more standardised key-based library.

It also becomes noisier as the number of supported languages grows. Three to five languages is comfortable. Ten starts to feel heavy in the component file.

The tradeoff in one sentence

You trade the flexibility of external translation files for a guarantee that TypeScript enforces: if your app compiles, every supported language has every string.

For small teams who maintain their own translations, that tradeoff is worth it.

If you want to try it:
react-scoped-i18n on GitHub

Localising your React app the "Tailwind" way: no keys & no JSON, just code

Amer Kočan — Sun, 08 Feb 2026 17:47:07 +0000

So, you want to localise your app

Most i18n solutions push you towards a familiar pattern:

Giant JSON/YAML files
Tediously "naming" your translations via keys
Made up string interpolation syntax
Constantly jumping back and forth between UI code and translation files

Which works fine, but the ceremony can start to feel a little tedious after a while.

I remember a few years ago, when I first picked up TailwindCSS, I was shocked by how much faster I could ship real UI once I started writing only what was needed.

I wanted the same feeling for i18n.

I want to introduce: `react-scoped-i18n 🌐`

The core idea here is: instead of global translation files and keys, translations live right next to the components that render them.

How does i18n typically look?

// en.json
{
  "profile": {
    "header": "Hello, {{name}}"
  }
}

// es.json
{
  "profile": {
    "header": "Hola, {{name}}"
  }
}

// Header.tsx
export const Header = () => {
  const { t } = useI18n();

  return <h1>
    {t("profile.header", { name: "John" })}
  </h1>;
};

Now, don't get me wrong, there's nothing wrong with this. It works and it's battle tested. But I kept running into the same friction:

Typescript can't help much without a lot of extra tooling
Translation keys give very little context about what actually renders
You cannot search the codebase for rendered text and find the component using it directly
String interpolation is custom syntax

So what does the “scoped” approach look like?

// Header.tsx
export const Header = () => {
  const { t } = useI18n();

  const name = "John";

  return (
    <h1>
      {t({
        en: `Hello, ${name}`,
        es: `Hola, ${name}`,
      })}
    </h1>
  );
};

No keys, no giant JSON files, no custom interpolation syntax, just code!

And, to be clear: This isn't meant to replace full-blown i18n platforms. It's an alternative for code-driven apps, and getting your app translated and localised fast.

The biggest benefits of this approach are:

- Typesafety 🩵

Since it's just code, everything is typesafe.

As an example here, I initialised the i18n context and specified I will be localising to English, Spanish and Slovenian:

createI18nContext({
  languages: [`en`, `es`, `sl`],
  fallbackLanguage: `en`, // already statically typed (inferred from 'languages' above
});

Later, when localising a component, I forgot the Spanish translation. This resulted in a Property 'es' is missing in type { en: string; sl: string; } typescript error , pictured here:

The main takeaway: missing translations or unsupported languages become compile-time errors instead of runtime surprises 😄.

- No naming of keys

The content is the key. Being able to search for rendered text and land directly in the component turns out to be a huge DX win. 😊

- No additional build steps

Since this is running directly within the React Context ecosystem, the setup takes about 20 seconds. There are no build steps to get this running. Just install the library, initialise the context, wrap your app with the exported provider and boom!

- Out of the box number, date, time & currency formatting ‼️

This library utilises the widely supported Internationalization API (Intl) for number, currency, date and time formatting. This means that there as long as you are following standard locale identifiers (en, en-UK, es, es-ES, etc.), you have all the various formatters available to you with zero extra configuration.

Typesafe "shared" translations

For common strings shared throughout the app, you can still define shared translations through the commons api:

createI18nContext({
  languages: ["en", "es"],
  fallbackLanguage: "en",
  commons: {
    continue: {
      en: "Continue",
      es: "Continuar",
    },
  },
});

And then access them (in a typesafe way that works well with your IDE's autocomplete):

<Button>{t(commons.continue)}</Button>;

Pluralisation is not ICU-based, but only ICU-inspired

Instead of enforcing strict ICU plural rules, tPlural lets each language define only the categories it actually needs.

{tPlural(count, {
  en: {
    one: `You have one apple.`,
    many: `You have ${count} apples.`,
  },
  sl: {
    one: `Imaš eno jabolko.`,
    two: `Imaš dve jabolki.`, // 👈 handling dual form in Slovenian that English does not have!
    many: `Imaš ${count} jabolk.`,
  },
})}

and you can also target specific values, if need be:

{tPlural(count, {
  en: {
    one: `You have one apple.`,
    many: `You have ${count} apples.`,
    42: `You have THE PERFECT amount of apples!` // 👈 target specific values outside of ICU category specification
  },
  es: {
    one: `Tienes una manzana.`,
    many: `Tienes ${count} manzanas.`,
  },
})}

When this isn't a good fit

This approach is developer-centric by design, so, if your workflow relies on:

external translators
"Crowdin" / "Lokalise" / similar tools
non-technical editors touching translation files
you have A LOT of supported languages

then this probably isn't the right approach.

But, if translations are written and maintained in code, and your supported language set is small-to-medium, the DX ends up being surprisingly nice.

If you're curious, the project is open source. You can check it out:

GitHub:
npm

Happy to hear any feedback!