RFC: Message extraction

[amannn]

Please use this thread to share feedback related to the RFC on message extraction.

See also the polls below:

1. Default format
2. Hook name

[amannn]

Question from @jurerotar:

A question I have is whether namespacing of messages will also be supported? I realize this is more of a SPA-related issue, but perhaps there are some use cases in Next.js apps where a developer is loading the localizations to the client and may want to split them up.

Answer:

Yep, namespaces are being considered, they are currently only briefly mentioned in regard to monorepos in the catalog generation section.

E.g.:

const t = useExtracted('namespace');
t('Hey there!');

… would generate e.g.:

{
  "namespace": {
    "5VpL9Z": "Hey there"
  }
}

I think the point is valid and this should be clarified more visibly (and perhaps not just be a "future exploration").

The ultimate goal for next-intl regarding splitting of messages for performance is #1, but as a stopgap solution some developers might find value in using some namespaces for this.

Does that answer the question?

[jurerotar]

Awesome, this looks really great!
Thank you very much for taking the time and clarifying this for me!

[amannn]

Quick poll: After reading the section on File formats & AI translation, which file format would you prefer as a default?

• 🚀 Portable object (.po)
• 🎉 Simple JSON (no contextual descriptions)
• 👀 Structured JSON (with vendor-specific format)

[amannn]

Yeah, there's a bit a tradeoff here I think. You could theoretically sort by file name, but if you move a translation from one file to another then there will also be an annoying diff where only the sorting changes. I'm not sure yet what the better option is …

[niieani]

btw. why no YAML option? (that's what we use)

[amannn]

Can you share an example snippet how this looks in detail? And is it based on a standard, or something you've defined for yourself?

[niieani]

Similar to your Structured JSON option, just in YAML. JSON has the issue of merge conflicts due to commas.
The output YAML is just a long array of strings, each defining the id, message and other options like the ones you would add in structured JSON. This is only to store the extracted strings. The consumable format that's downloaded by the app is either JSON files or JSON in JS files (extra trick for perf) + the default/fallback language embedded by the transpiler in the t() calls.

[amannn]

I see, got it! Yeah I think custom formatters will likely be necessary, just because people have different preferences here. Maybe support for some popular ones OOTB would be good though.

extra trick for perf

Super interesting, thanks for sharing!

[amannn]

Another poll: Do you prefer useExtracted or useInlined as the hook name?

import {useExtracted} from 'next-intl';

function InlineMessages() {
  const t = useExtracted();
  return <h1>{t('Look ma, no keys!')}</h1>;
}

import {useInlined} from 'next-intl';

function InlineMessages() {
  const t = useInlined();
  return <h1>{t('Look ma, no keys!')}</h1>;
}

Please vote with your preference:

• 🚀 useExtracted
• 🎉 useInlined

I'd also appreciate if you leave a comment here explaining why you prefer a particular option! (or why the alternative is bad)

[amannn]

It's an interesting idea, yes!

You could theoretically also rename the returned function for slimmer call sites:

const { inline: t } = useTranslation();
t('Hey there!');

But I don't know, it just seems a bit noisy to me if you have this in a large part of your components …

There are some earlier API ideas related to this in #1904 (comment).

The one I liked best is this one:

import {useTranslations} from 'next-intl';

function InlineMessages() {
  const t = useTranslations().extract();
  t('Hey there!');
}

It's definitely still a consideration.

There were some arguments that made me favor a separate hook though:

1. Async Server Components don't allow hook calls, therefore we'd also need const t = await getTranslations().extract(). getTranslations() already returns a promise, so this is in fact a bit of a hack where I'd have to patch extract on a promise type. Not quite sure if there could be other side effects caused by this.
2. Easy to lint for in case you want to use exclusively one or the other.
3. (this is a guess) Maybe it confuses AIs less, because the useTranslations API of next-intl has been around for a long time.
4. (nice-to-have) Easier to detect with the analyzer to extract strings.

Ultimately, I favored the separate hook also because it's just a bit more minimalistic to write and read … Not sure yet though.

What do you think?

[raphaelbadia]

I voted for useExtracted because it sounds good to me, I understand clearly what it means.
I feel like I would forget the name useInline, and I'd be like "What's the function called again" ?

[jurerotar]

This is a bit more on the hacky side, but how about adding the inline method to t directly?

import { useTranslations } from 'next-intl';

function InlineMessages() {
  const t = useTranslations();
  t.inline('Hello {name}', {name: 'Jane'});
}

T function signature is then either an invokable function or an object with this method. It doesn't address your third point though sadly :(

[amannn]

@raphaelbadia I can relate to that, yes!

@jurerotar Yep, theoretically also a possibility! However, next-intl currently also supports t.rich & t.markup and these will need to be supported for extracted messages too. I have a loose thought of getting rid of them in favor of a generic t function that would just return the right thing based on the arguments it receives, but it's still a bit further down the road—I wouldn't want it to block adoption of message extraction. So for the time being, message extraction should be compatible with those existing APIs.

[ceolinwill]

I don’t have a strong opinion, but useInline feels too vague since it could mean anything (not necessarily an inline translation). I’d probably prefer something like useInlineTranslation because it makes the purpose clearer.

[amannn]

Some thoughts on rich text formatting from @niieani:

As far as rich text, there's a way to do it while using string literals. I might have not mentioned that in my talk, but we had a solution, which was something like this:

const Bold = ({children}) => <b>{children}</b>
t(`This is <Bold>${userName}</Bold>.`, { components: { Bold } })

basically, we parse the string literal with the DOMParser and construct a React Array by wrapping any components with the components passed in as the component resolvers in the options passed to t function
this also works with nesting
and we statically analyze the strings during compilation to ensure that all the tags are correct and closed
this also means you can insert any component inside of any string, not just ones that wrap text (if that's something you needed) and is easy to understand by many translation tools.

I think it's an interesting approach, somewhere in the middle of using direct concatenation and using arguments in ICU strings. Kind of a hybrid solution in contrast to what the RFC currently discusses.