Improved type-safety for t.raw() and improved autocomplete.

[davemecha]

I have a project where I wanted to create a type-safe component to display stuff based on the content of my translations file structure like this:

// Type-safe dynamic keys - only allows 'john' | 'jane'
export function Testimonial({ itemKey }: { itemKey: ChildKeySegments<'portfolio.testimonials.items'> }) {
  const t = useTranslations('portfolio');
  const testimonial = t.raw(`testimonials.items.${itemKey}`);
  // Type: { name: string, text: string, rating: number }

  return (
    <div>
      <blockquote>{testimonial.text}</blockquote>
      <footer>
        <p>{testimonial.name}</p>
        <div>
          <p>{'⭐'.repeat(testimonial.rating)}</p>
        </div>
      </footer>
    </div>
  );
}

• I needed a helper type to retrieve the direct child segments for a given translation key. I accomplished this with ChildKeySegments
• I needed a t.raw method, that supports autocomplete for all the possible partial path segments, that may be passed, not only for the message keys, as the original next-intl API supports.
• I wanted the return type of t.raw to be correctly typed. So an object containing multiple messages should be correctly typed. The original API always returned any since it only supported message keys.

I don't know, if there is a more elegant way to achieve this. I'd be happy to get some suggestions.

I also would like to know, why the typing of t.raw is not more specific. Is this on purpose? If not, do you think, it might be a good idea to create an issue to improve the typing on this?

I vibe coded a demo repository to showcase this. Please ignore the irrelevant slop in the repo. The solution itself was hand crafted by me in one of my projects. And to get a quick demo, I generated the project in this repo with firebase studio.

https://github.com/davemecha/next-intl-improved-typing-demo

I hope this is a good place for a discussion like this. I'm new to this project, so please close this topic if it's not matching well.

[amannn]

Hey, thanks for raising this, your thoughtful comment and the demo repo!

t.raw was in fact added quite early in the project, more than 4 years ago in [email protected] to render raw HTML markup as it's shown in the docs. I found however that it was frequently used for array-esque data, like it's also shown in your example.

This unfortunately has some downsides, like it not working well with features like these:

1. Message extraction #1904 (a first experimental release likely coming this week!)
2. Automatic tree-shaking of messages #1
3. Ahead-of-time compilation of messages #962
4. Validating messages

Due to this, the next-intl docs suggest a different pattern for arrays of messages.

In your case, you could also implement the testimonials like this:

<TestimonialCard 
  name={t('testimonials.items.john.name')}
  text={t('testimonials.items.john.text')}
  rating={5}
/>
<TestimonialCard 
  name={t('testimonials.items.jane.name')}
  text={t('testimonials.items.jane.text')}
  rating={5}
/>

I know it might look almost too simple, but it really unlocks powerful optimizations like the ones mentioned above.

To be honest, I'm thinking of deprecating t.raw at some point due to the limitations it has and also pointing developers into directions that will come with tradeoffs down the road.

I think the typical use cases for t.raw are:

1. Array data (better served with explicit, non-dynamic keys)
2. Moving "data" out of your app code, like the rating in your example (can either be hardcoded, moved to a custom data structure in your codebase, or moved to a CMS or backend)
3. Raw HTML markup (better served with local MDX, or a CMS)

These are my current thoughts, would be curious to hear your perspective on this!

[davemecha]

Hey @amannn,

Thanks for taking the time to reply. I spent some time digging into the use cases and challenges around t.raw and the related features you mentioned. I totally understand how these features conflict with any kind of dynamic keys, like in the examples I described.

That said, I still hope t.raw won’t be deprecated. I think there might be ways to keep at least partial support for dynamic keys, even with your proposed features implemented. Not sure if this would be feasible, but here are a couple of rough ideas (without digging too deep into the proposals for these features):

• Message extraction #1904: Message extraction could skip dynamic keys when collecting messages and ignore namespaces containing dynamic keys during pruning. (If used with special functions like useExtracted, extraction would still apply. Any dynamic key under namespaces that use the current API, e.g. useTranslations and a derived t function, would be ignored.)
• Automatic tree-shaking of messages #1: Tree shaking could work similarly: include all keys of namespaces that contain dynamic keys. This might even be improved through template string detection (for example, detecting t(`foo.${bar}`) and then including all subkeys of foo in the bundle).

---

My use case is quite simple: I manage content for a personal profile page. The number of translation keys is small, so message extraction and pruning aren’t that relevant to me. What matters more is having some flexibility and convenience when composing components.

Here’s a simplified example of my structure:

    ...
    <ResumeSheet pageNumber={2}>
      <section>
        <ResumeHeading period={t('sections.experience.heading1period')}>
          {t('sections.experience.heading1')}
        </ResumeHeading>
        <ResumeCard itemKey="aProject" />
        <ResumeCard itemKey="anotherProject" />
        <ResumeCard itemKey="yetAnotherProject" />
        <ResumeCard itemKey="coolProject" />
      </section>
    </ResumeSheet>
    
    <ResumeSheet pageNumber={3}>
      <section>
        <ResumeHeading>{t('sections.experience.heading2')}</ResumeHeading>
        <ResumeCard itemKey="aCustomer" />
        <ResumeCard itemKey="anotherCustomer" />
        <ResumeCard itemKey="customerX" />
        <ResumeCard itemKey="customerY" />
      </section>
    </ResumeSheet>
    ...

Each ResumeCard references a nested structure in my translation files (not just an array of strings), which keeps things easy to maintain without needing a CMS or backend. For a small personal project, this lightweight approach works best. Much less verbose than writing something like this:

<ResumeCard 
  role={t('sections.experience.items.aProject.role')}
  companyName={t('sections.experience.items.aProject.company.name')}
  companyLocation={t('sections.experience.items.aProject.company.location')}
  period={t('sections.experience.items.aProject.period')}
  highlights={[
    t('sections.experience.items.aProject.highlights.1'),
    t('sections.experience.items.aProject.highlights.2'),
    t('sections.experience.items.aProject.highlights.3'),
    t('sections.experience.items.aProject.highlights.4'),
  ]}
  ...
/>

I'd have to replicate the whole structure of my translation file for each item. Using it dynamically as in my example above is much more convenient and practical for me and I get great typescript support for this, like autocomplete and implicit validation.

---

One more question on this: would adding improved typing to t.raw alone cause problems for the existing tooling? I’m not thinking about changing its runtime behavior, just tightening the types so consumers get better autocomplete and DX.

I also understand if this isn’t the direction you want to optimize for, given the project’s focus on more static and predictable setups, and that smaller or more dynamic use cases like mine might be out of scope. (I'm happy with my wrapper solution for now. :D ) - Maybe I will consider a CMS or using MDX for the future (if you decide to deprecate t.raw ;) ).

[amannn]

Thanks for sharing your thoughts!

And yes, I think to some extend t.raw can continue to work for the features I mentioned, e.g. i18n-check also has handling for dynamic key access (pretty much what you described as well).

The more problematic one is probably #962 — or at least if you have arbitrary data structures in your messages. If you only use t.raw for code organization, this might still be fine.

In regard to useExtracted, the use case is btw. slightly different. We're not just extracting keys of messages (that's what intl-watcher already does—even with support for dynamic keys), but it will be a new API to define messages inline and extract them with an auto-assigned key.

E.g. for your example, it might look like this:

import {useExtracted} from 'next-intl';

const t = useExtracted();

<TestimonialCard 
  name={t('John Doe')}
  text={t('Best product ever!')}
  rating={5}
/>

So in regard to avoiding verbose keys, this could be a helpful alternative as well. The current implementation doesn't even support t.raw, since it doesn't really make sense for this paradigm.

But yeah, I see your point about this being verbose when using explicit IDs!

As for improving the typings for t.raw: There are just quite some other priorities at the moment for the project, so if this can be solved in userland, I'd hope that's good enough for now! I just don't know if the API will stick around forever, therefore improving the DX of using it (for a use case it wasn't designed for), is just not really what I'd like to introduce currently—I hope you can understand!