Make the translation function fully type-safe

[karol-majewski]

🚀 Feature Proposal

With the latest advancements in TypeScript, it's now possible to infer the correct paths from an object type. TypeScript 4.1 introduces recursive conditional types, and there is a PR open that will enable string type concatenation on the type level.

Motivation

18next.t accepts arbitrary strings. This allows silly human errors, since it's easy to make a typo.

Example

I put together a TypeScript Playground illustrating the improved definition.

Once microsoft/TypeScript#40336 is merged and released, the improved definition can be put in a separate file loaded only for the ones using the minimum required TypeScript version. In package.json, it should say:

{
    "typesVersions": {
        ">=4.1.0-0": {
            "*": [
                /* Path to the new definition */
            ]
        }
    }
}

[rosskevin]

Very nice! Once the new TS is released, we can accept a PR for this. We may need to think about modifying our usage tests so that we can properly test it, we currently do not have any expect error notations being used.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[raynor85]

This should be reopened, it is a must have feature and we already have a solution for it.

[jamuhl]

stalebot

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[akosbalogh]

up!?

[pierpo]

I started a PR to allow this. The deeply typed translations work locally on my project with your work + my PR, @karol-majewski 😊

[karol-majewski]

@pierpo I like your approach very much. It allows the consumers to decide whether they want things to stay as they are, or if they prefer full type safety for the price of slightly degraded performance. Also, it doesn't introduce much complexity to the core package.

Definitely worth considering!

[pedrodurek]

Hey guys, while we’re working on the documentation, I just want to clarify a few things about the types introduced on the react-i18next lib.

1 - For those who opt not to have the t function fully type-safe, it should work as before, so it shouldn’t have breaking changes and shouldn’t increase the compilation time (since it’ll fallback to the original types).
2 - For those who choose to have the t function fully type-safe, it’ll type not only the keys, but also the return type (that’s great when you’re using returnObjects set to true). 
3 - The compilation time only will increase according to the number of keys (since it’ll map all keys recursively). At SkipTheDishes, we have a few projects with more than 1500 keys, and it works smoothly. In our tests, we checked with more than 7k keys (you can check it here https://github.com/pedrodurek/i18n-type-tests).
4 - The types add to the core project (react-i18next) are a bit overwhelming indeed, but just because they aim to handle all features that the library supports, such as, single namespace, multiple namespaces, no namespaces, objects and arrays, fallback, template literal, keys and return typed, etc.
5 - The only setup needed in order to get the t function fully type-safe is the type augmentation, as we can see in this example: https://github.com/i18next/react-i18next/blob/master/example/react-typescript4.1/no-namespaces/%40types/react-i18next/index.d.ts
It seems to be a complex setup, but it isn’t, and that’s the only way available by Typescript. Other libraries use the same approach (styled-components https://styled-components.com/docs/api#create-a-declarations-file), and it’ll become even more common as Typescript become more powerful.

Sorry for those who get affected with the bugs introduced in the first versions of v11.8.x. For now, we managed to solve all issues reported by users who choose not to use this feature (so it doesn’t look like a breaking change). And we’ll answer and address all issues reported for those who are interested.

We’re working hard to bring a great experience to developers. This feature not only helps developers (with autocomplete and type check), but also prevents clients from complaining about strings like this dashboard.title on the webpage/mobile app (that happens with us more than once), particularly when we’re maintaining a project and ended forgetting to update a key.

[jamuhl]

@karol-majewski sorry for missing this issue so long...currently I have no clear view if this can be closed with the last comment of @pedrodurek or if we're still waiting for some PR?

[pedrodurek]

Hey @jamuhl, If people are interested, I can move types from react-i18next to here, so we can also rely on the algorithm that infers keys and return types for the i18n t function as well. The only problem would be the breaking changes.

[jamuhl]

@adrai guess this would be worth a breaking release for typescript users and improve the experience using i18next

[adrai]

So the opposite of what I tried to describe here: i18next/react-i18next#1361 (comment) ?
So this means also if using react-i18next or any other i18next plugin, tge appropriate i18next version needs to be installed...

So why not move all types completely out to a single i18next-types module? (it was like that in the beginning)

[jamuhl]

fully typesafe translations belongs to both i18next as is and react-i18next - so having them here sounds right to me.

Moving types out of the project does lead to even worse DX - I guess

[adrai]

ok, then we need to live with the fact, each time some react-i18next specific type is changing, i18next needs to be updated...

[pedrodurek]

Yeah, the best approach would be to move all types to here, so both libraries can leverage the type-safe feature. Alternatively, we can move all types to https://github.com/DefinitelyTyped/DefinitelyTyped, but it'd be hard to keep it updated, built-in types are always preferable.

[adrai]

Ok, let's try to move them to here

[pedrodurek]

Great, I'll be focusing on that in the coming days/weeks, I'll be also testing compilation time performance, so it may take some time.

[davloperez]

How is this going @pedrodurek ? I think this feature is really cool and expected :)

[pedrodurek]

Hey @davloperez, I expect to have something in place by the end of this month/beginning of February

[OliverJAsh]

As far as I can see, the change proposed here wouldn't achieve full type safety because it would still be possible to pass incorrect parameters. Example:

{
    "intlNumber": "Some {{val, number}}"
}

i18next.t('intlNumber', { val: {} });

This should error at build time because we're passing an object to an argument (val) that expects number. At runtime the user will see the string Some NaN.

FormatJS/react-intl has the same issue, although they do have a lint rule that helps a bit (enforce-placeholders).

[jamuhl]

@OliverJAsh what you're asking is impossible to achieve - translations might come from backend, further those translations are plain strings and can't be handled by typescript, either because it's just a string or not even available during coding...

only option I would see is changing from string based translations to hardcoded template strings in a JS file for development...

but might be I'm missing something or someone has a super clever idea...

[OliverJAsh]

That's certainly the case if it's coming from a backend, but in many cases the strings are defined statically in the code, so this isn't a necessary limitation. In that case, there are a few ways we can achieve type safety for parameters:

• We can convert message strings to TypeScript functions with types for parameters. See Vocab for example.
• We can use a DSL such as JSX to define the messages and extract them to message strings automatically. See Lingui for example. Also see this experiment I created which provides a DSL for creating the ICU Message AST and then TypeScript can infer types from this.
• It's probably possible to use TypeScript template literal types to extract types from the message string, but I haven't seen anyone experiment with this yet.

[jamuhl]

@OliverJAsh Feel free....as long it's optional and only affects typescript users I got nothing against it...just not something I can help with as I don't use typescript and won't ever use it.

[pedrodurek]

Hey @OliverJAsh, right now, typescript doesn't support getting literal values from JSON files yet microsoft/TypeScript#32063

[tkow]

I recently came up with fully inference solution of t's function type in Typescript version >= 4.1.

This type definition is followed by typescript playground.

In short, we can infer all arguments from typed dictionary object by as const and it can specify useTranslation and, if necessary earlier initialization its type by declare modules or wrap useTranslation function using my example's defined types like

interface NewWithTFunc<TranslateOptions extends Record<string, object>, TranslateTemplate extends object>{
    <TKeys extends keyof TranslateOptions & keyof TranslateTemplate> (key: TKeys | TKeys[], options?: TranslationOptions<TranslateOptions[TKeys]>) : TranslateTemplate[TKeys];
}

// For assuming useTranslation typed with dummy t function
const useTranslation = <TranslateOptions extends Record<string, object>, TranslateTemplate extends object>() => {
    return {
        t: (() => {}) as any as NewWithTFunc<TranslateOptions, TranslateTemplate>
    }
}

const useAppTranslation = () => {
  return useTranslation<TranslateOptions, TranslateTemplate>()
}

What do you think adding this implements to your library?

This feature can be seen in L135-138 in this example.

@OliverJAsh
I still have problem in your point. Option's type cannot be inferred and my solution can infer only key name.
And I may miss some features in i18next. I hadn't known way to specify type with comma.I may be able to extract key name in this pattern and try to do it.
I achieved infer key's name with comma and improve typescript playground's example.

Finally, I found we may infer somewhat format function in this page as possible like pre-defined like {number: Number} types dictionary and extract type string per placeholders, but supporting all format function is very tough to maintain (especially in case they have extra parameters with placeholder). So it may be better to define type per format functions, and including them in TranslationOptions type though it's not fully type-safe.

[justin-barca-at-camis]

I decided to have all my translations in TS so that I could make them type-safe. I devised this little TS scheme to ensure that all translations for all languages and all namespaces are defined.

export enum TRANSLATION_KEYS {
  LOGIN,
}

enum LANGUAGE {
  EN = 'en',
}

enum TRANSLATION_NAMESPACES {
  DEFAULT = 'translation',
}

type Translation = {
  [K in TRANSLATION_KEYS]: string;
};

type TranslationResources = {
  [L in LANGUAGE]: TranslationNamespaces;
};

type TranslationNamespaces = {
  [N in TRANSLATION_NAMESPACES]: Translation
};

export const resources: TranslationResources = {
  [LANGUAGE.EN]: {
    [TRANSLATION_NAMESPACES.DEFAULT]: {
      [TRANSLATION_KEYS.LOGIN]: 'Login',

    },
  },
};

EDIT: the following statement is incorrect, numbers as keys are okay in resources but you can't call t with a number. However, if you cast it to string, it works and the useCustomTranslation enforces key safety for the t function.

However, this doesn't work properly because the enum values are numbers. It will work if you manually assign a string to each of the TRANSLATION_KEYS and I'd really like to avoid this. Is there any way that this library could also support numbers as translation keys?

I've thought of ways around this with utility functions. You can re-map the keys of each translation set to be strings (or just be careful and string-interpolate all them) and then create a custom t function that would take the numeric keys and cast them to string.

export const useCustomTranslation = () => {
  const useTransOriginal = useTranslation();
  const numFriendlyT = (keyOrKeys: TRANSLATION_KEYS | TRANSLATION_KEYS[], options?: TOptions | string) => {
    if (Array.isArray(keyOrKeys)) {
      return useTransOriginal.t(keyOrKeys.map(key => `${key}`), options);
    }
    return useTransOriginal.t(`${keyOrKeys}`, options);
  };
  return { ...useTransOriginal, t: numFriendlyT };
};

Thoughts?

[OliverJAsh]

As far as I can see, the change proposed here wouldn't achieve full type safety because it would still be possible to pass incorrect parameters.

If anyone is interested, this is how we solved this problem and achieved full type safety for our translated messages: https://twitter.com/OliverJAsh/status/1521505324791967744

[adrai]

As far as I can see, the change proposed here wouldn't achieve full type safety because it would still be possible to pass incorrect parameters.

If anyone is interested, this is how we solved this problem and achieved full type safety for our translated messages: https://twitter.com/OliverJAsh/status/1521505324791967744

@pedrodurek this sounds interesting, isn't it? but probably not easy applicable to i18next, right? What's your opinion?

[ashkan-pm]

Any idea when this feature is going to be added?

[pedrodurek]

The migration is almost done, I believe I'll have a PR opened by the end of the next week

[gallaouim]

is this Feature already in Production ?

[JohnHallstrom]

is this Feature already in Production ?

I think we're still patiently awaiting its linked pull request getting finished and merged:

• Make the translation function fully type-safe #1775