Enhanced Type Safety in TypeScript 4.1

The latest version of TypeScript, TS 4.1, introduces support for typed string-key lookups and interpolation using template literal types.

With this new feature, we can now access dictionary keys or object paths deeply by providing a string argument:

t("footer"); // ✅ { copyright: "Some copyrights"; }
t("footer.copyright"); // ✅ "Some copyrights"
t("footer.logo"); // ❌ should trigger compile error

Let's delve into how we can define a suitable return type for the translate function t, how to emit compile errors for non-matching key arguments, provide IntelliSense support, and explore an example of string interpolation.

1. Key Lookup: Return Type

// Returns the property value from object O given the property path T, otherwise 'never'
type GetDictValue<T extends string, O> =
    T extends `${infer A}.${infer B}` ?
    A extends keyof O ? GetDictValue<B, O[A]> : never
    : T extends keyof O ? O[T] : never

function t<P extends string>(p: P): GetDictValue<P, typeof dict> { /* implementation */ }

Check out the Playground to play with the code: Playground

2. Key Lookup: IntelliSense and Compile Errors

To enforce type safety and provide IntelliSense suggestions, we use conditional types like so:

// Returns the same string literal T if props match, else 'never'
type CheckDictString<T extends string, O> = 
  T extends `${infer A}.${infer B}` ?
  A extends keyof O ? `${A}.${Extract<CheckDictString<B, O[A]>, string>}` : never
  : T extends keyof O ? T : never

function t<P extends string>(p: CheckDictString<P, typeof dict>): GetDictValue<P, typeof dict> { /* implementation */ }

Explore the Playground for interactive examples: Playground

3. Interpolation

Incorporating string interpolation into translations:

// Helper types for string interpolation
type Keys<S extends string> = S extends '' ? [] :
    S extends `${infer _}{{${infer B}}}${infer C}` ? [B, ...Keys<C>] : never

type Interpolate<S extends string, I extends Record<Keys<S>[number], string>> =
    S extends '' ? '' :
    S extends `${infer A}{{${infer B}}}${infer C}` ?
    `${A}${I[Extract<B, keyof I>]}${Interpolate<C, I>}`
    : never

Example:

type Dict = { "key": "yeah, {{what}} is {{how}}" }
type KeysDict = Keys<typeof dict["key"]> // ['what', 'how']
type I1 = Interpolate<typeof dict["key"], { what: 'i18next', how: 'great' }>;;
// Result: "yeah, i18next is great"

function t<K extends keyof Dict, I extends Record<Keys<Dict[K]>[number], string>>(k: K, args: I): Interpolate<Dict[K], I> { /* implementation */ }

const ret = t('key', { what: 'i18next', how: 'great' } as const);
// Output: "yeah, i18next is great"

Try it out on the Playground: Playground

For more details, refer to the discussion on deep keyof of a nested object: Typescript: deep keyof of a nested object

Note: These advanced typing features may have limits due to complexity and recursion depth restrictions in TypeScript compiler.

Good news! React-i18next now includes native support for this feature. While official documentation may be lacking, the source code contains useful comments to guide you.

If your translations are stored in

public/locales/[locale]/translation.json

and English is your main language:

// src/i18n-resources.d.ts

import 'react-i18next'

declare module 'react-i18next' {
  export interface Resources {
    translation: typeof import('../public/locales/en/translation.json')
  }
}

For those utilizing multiple translation files, remember to include all of them in the Resources interface, each identified by namespace.

Don't forget to add

"resolveJsonModule": true

to your tsconfig.json if you're importing translations from a json file.

To achieve similar functionality, one can create a TranslationKey type and utilize it in the useT hook along with a custom Trans component.

1. Start by creating a translation.json file

{
  "PAGE_TITLE": "Product Status",
  "TABLES": {
    "COUNTRY": "Country",
    "NO_DATA_AVAILABLE": "No price data available"
  }
}

2. Generate the TranslationKey type using generateTranslationTypes.js

/**
 * This script generates the TranslationKey.ts types that are used from
 * useT and T components
 *
 * ...
 */

const translation = require("./translation.json")
const fs = require("fs")

function extractKeys(obj, keyPrefix = "", separator = ".") {
  const combinedKeys = []
  const keys = Object.keys(obj)

  keys.forEach(key => {
    if (typeof obj[key] === "string") {
      if (key.includes("_plural")) {
        return
      }
      combinedKeys.push(keyPrefix + key)
    } else {
      combinedKeys.push(...extractKeys(obj[key], keyPrefix + key + separator))
    }
  })

  return combinedKeys
}

function saveTypes(types) {
  const content = `// generated file by src/i18n/generateTranslationTypes.js

type TranslationKey =
${types.map(type => `  | "${type}"`).join("\n")}
`
  fs.writeFile(__dirname + "/TranslationKey.ts", content, "utf8", function(
    err
  ) {
    if (err) {
      console.log("An error occurred while writing to File.")
      return console.log(err)
    }

    console.log("file has been saved.")
  })
}

const types = extractKeys(translation)

console.log("types: ", types)

saveTypes(types)

3. Implement the useT hook for handling translations using the TranslationKey type

import { useTranslation } from "react-i18next"
import { TOptions, StringMap } from "i18next"

function useT<TInterpolationMap extends object = StringMap>() {
  const { t } = useTranslation()
  return {
    t(key: TranslationKey, options?: TOptions<TInterpolationMap> | string) {
      return t(key, options)
    },
  }
}

export default useT

4. Create a custom component similar to Trans for rendering translated content

import React, { Fragment } from "react"
import useT from "./useT"
import { TOptions, StringMap } from "i18next"

export interface Props<TInterpolationMap extends object = StringMap> {
  id: TranslationKey
  options?: TOptions<TInterpolationMap> | string
  tag?: keyof JSX.IntrinsicElements | typeof Fragment
}

export function T<TInterpolationMap extends object = StringMap>({
  id,
  options,
  tag = Fragment,
}: Props<TInterpolationMap>) {
  const { t } = useT()
  const Wrapper = tag as "div"
  return <Wrapper>{t(id, options)}</Wrapper>;
}

export default T

5. Utilize useT and T components to render content with type-checked ids

const MyComponent = () => {
    const { t } = useT()


    return (
        <div>
            { t("PAGE_TITLE", {count: 1})}
            <T id="TABLES.COUNTRY" options={{count: 1}} />
        </div>
    )
}

To ensure type safety, the official documentation provides a detailed explanation: https://www.i18next.com/overview/typescript

For example:

// importing original type declarations
import "i18next";
// importing all namespaces (for default language only)
import ns1 from "locales/en/ns1.json";
import ns2 from "locales/en/ns2.json";

declare module "i18next" {
  // Extending CustomTypeOptions
  interface CustomTypeOptions {
    // custom namespace type, if modified
    defaultNS: "ns1";
    // custom resources type
    resources: {
      ns1: typeof ns1;
      ns2: typeof ns2;
    };
    // other modifications
  }
}

Excellent response @ford04! However, there seems to be a slight issue with Keys and Interpolate types. If you use it in this particular manner without a variable at the end of the string, the interpolation may not recognize it. To address this issue, you can make the adjustment as follows:

export type Keys<S extends string> =
  S extends `${string}{{${infer B}}}${infer C}`
    ? C extends `${string}{{${string}}}${string}`
      ? [B, ...Keys<C>]
      : [B]
    : never;

type Interpolate<
  S extends string,
  I extends Record<Keys<S>[number], string>,
> = S extends ''
  ? ''
  : S extends `${infer A}{{${infer B}}}${infer C}`
  ? C extends `${string}{{${string}}}${string}`
    ? `${A}${I[Extract<B, keyof I>]}${Interpolate<C, I>}`
    : `${A}${I[Extract<B, keyof I>]}`
  : never;

For reference, check out this playground example: Playground

A new command line interface (CLI) I developed enables the creation of dts type definition files from various json configurations. This tool is available for testing purposes. As of now, the latest TypeScript 4 features do not fully support all aspects of i18next, prompting me to opt for code generation.

Visit this link to access the tool: https://www.npmjs.com/package/@liuli-util/i18next-dts-gen

I have devised a solution that extracts the key (including nested keys) from a dictionary.

declare module 'i18next' {
    import deTranslation from 'path/to/dictionary.json';

    type Translations<T = typeof deTranslation> = T;
    type ConcatKeys<T, U> = T extends string ? `${T & string}.${U & string}` : never;

    // Create a recursive type for nested keys
    type NestedKeys<T> =
        T extends object ? {
                [K in keyof T]: K | ConcatKeys<K, NestedKeys<T[K]>>;
            }[keyof T] :
            string;

    type TranslationKeys<T> = NestedKeys<T>;
    interface TranslationFunction<T> {
        <K extends TranslationKeys<T>>(key: K, nestedKeys?: string[]): string;
    }
    export const t: TranslationFunction<Translations>;
}

This allows for suggestions and validation to be implemented. https://i.sstatic.net/dka4x.png