useExtracted feedback

[amannn]

Please use this thread to share feedback related to useExtracted.

This is my public TODO list for the feature: #2087 (but please keep the feedback here)

[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)

[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!

[Carlwirkus]

The default not being JSON or structured JSON feels like a mistake. I'd be optimising for familiarity rather than efficiency. Provide an option for custom outputs if it's really that much better.

Cool idea though! keen to give it a go.

[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)

[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.

[priyajeet]

Having the word Translation in the hook name will make the hook more self documented imo. Otherwise people might have to proxy hook to make it more readable. useInline and useExtracted don't really mean much imo unless you look at where its being imported from which may be collapsed away in github reviews.

[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.

[amannn]

A first release is out in next-intl@4.5! 🎉

Learn more:

• Blog post
• X post
• Bluesky post

[ceolinwill]

Thanks again for working on this. I wanted to share some initial feedback:

1. Source string in PO files

Right now, the msgid in PO files uses a random ID like Ju9oB+. This makes it harder to translate, since we have to check the source file to understand what each key refers to.

In other frameworks using Gettext (like Phoenix), the msgid stores the actual source string. For example:

msgid "Create an account"
msgstr ""

It would be great to have an option for this behavior, or at least include the source string as a comment above each msgid.

2. Deterministic compilation

Currently, every next build changes the order of items in the PO files, even when nothing in the code has changed. I tested this a few times and it happens consistently every time.

Ideally, the output should be deterministic and only update when translations are actually added, modified, or removed.

[amannn]

Hmm, that doesn't sound right. Let me have another look, I've probably missed something. I'll get back to you!

[amannn]

Should be fixed with this: #2103 (comment)

[ceolinwill]

@amannn Quick update. I might have run into another issue, but I’m not fully confident because it’s hard to reproduce.

A few times, all translations in a locale were replaced with empty strings. I first saw it while testing the canary build when pt.po translations suddenly got wiped, but I couldn’t reproduce it and assumed I had deleted that file by mistake and it had to be rebuilt.

However, now it happened twice on my branch using 4.5.2. I’ve probably run the build 20+ times and only saw this happen 3 times, so I don’t have a reliable repro. Just mentioning it in case it helps you spot something. This happened twice with my pt.po file and once with es.po, never with the source en.po file.

[amannn]

Thanks, I'll check if I can find something suspicious that could cause this. I'll follow up here!

[amannn]

#2036 (reply in thread)

[ceolinwill]

Something else I just noticed:

Fallback for untranslated strings

Right now, untranslated strings render as empty. It would be great if they could fall back to the default locale.

For example, if a string isn’t yet translated to es, it could display the default version (eg en) instead of an empty value.

[amannn]

You can already do that in i18n/request.ts:

import {getRequestConfig} from 'next-intl/server';
 
export default getRequestConfig(async () => {
  const userLocale = 'es';
  const defaultLocale = 'en';

  const userMessages = (await import(`../../messages/${userLocale}.json`)).default;
  const defaultMessages = (await import(`../../messages/${defaultLocale}.json`)).default;
  const messages = {...defaultMessages, ...userMessages};

  return {
    messages,
    locale
  };
});

You can replace .json with .po depending on the formatter that you're using, but since this will import the messages as plain JS objects, the pattern is exactly the same.

In theory, we could display the source text in development as a fallback, but this would suddenly vanish once you build for production. So my current understanding is that it might be clearer if we let users do this themselves in either case, to have more flexibility and to avoid surprises.

Does that make sense?

[ceolinwill]

Yeah, that's a good idea. Thanks!

[bennajah]

This works only when the extracted messages feature is not used.

When using the feature, for example with the default locale set to en, we have:

en.json

{
   "AAA": "text1",
   "BBB": "text2",
}

de.json

{
   "AAA": "",
   "BBB": "",
}

When calling useExtracted() or await getExtracted() on untranslated pages, only empty strings are shown — because the untranslated message files are automatically generated with empty string values.
Even if you manually clear or delete these files, they get recreated automatically.

[amannn]

Right, but it's really up to you to merge however you like, e.g. not using entries with empty messages. Extracting the empty strings to target locales is something that happens by design, which should act as a call to action in your git diffs to insert missing translations. But you can also do locales: ['en'] if you don't want to extract to target locales. Or define a custom formatter in the future if you have more specific requirements.

[bennajah]

Is the package tree-shakeable and does it bundle only the messages used by the current page — similar to how @inlang/paraglide-sveltekit works for SvelteKit?

[amannn]

Last time I checked, paraglide used per-message splitting. This is in contrast to next-intl, which uses per-locale splitting.

The former can help with tree shaking if you support a few locales, but the problem is that it will bundle all variants for all languages that you support. E.g. the Ethereum website localizes to 69 languages, therefore for projects of this size this is just not really an option to begin with.

With per-locale splitting, we need to solve the problem the other way round. Today, you can optimize manually if you like, but automatic tree-shaking is planned for the future.

The package itself is of course tree-shakeable (it's ESM-only) and will only bundle the features you really use.

Hope that helps!

[c0nsoleg]

Should it work with monorepo? Seems like message aren't picked up from packages at build or dev.

[amannn]

Monorepos are supported, yes. The docs are a bit sparse in regard to this though, I'm planning to include more.

See also: https://x.com/jamannnnnn/status/1987163883165860145

But did you encounter a bug? If so, can you share a reproduction?

[bennajah]

i dont have src folder and i want extract from root folder

so when use

srcPath: "./",

instead of

srcPath: ["./actions", "./app", "./components", "./lib", "./schemas"],

messages not extracted

[amannn]

Thanks, I'll look into this! I think it's likely happening due to a guard against traversing your node_modules missing, therefore the initial scan doesn't complete (or very late). I'll share an update here once this is fixed.

In the meantime, you can use an array of explicit folder names.

[amannn]

@bennajah This should be fixed in next-intl@4.5.2!

[priyajeet]

Will this work if t is passed into a plain old function?

[amannn]

Only statically analyzable calls like t('Hello!') are supported, anything dynamic like t(key) will print an error. I'll add some docs for this that covers how to write code in a statically analyzable way, covering common patterns.

Can you share your use case why you'd want to pass t into a function as a parameter?

EDIT: Static analysis was added now

[priyajeet]

Specifically for code organization. Say I want to translate based on an error code, I may have a function that takes the t function and code and has a gazillion switch case statements returning a different string based on code. And then I show this string to the user via a banner, say toast(). Likewise this function can be also used somewhere else. Now, one can make the function a hook and then useExtracted can be used in it, but then that is not re-usable in non-react parts and testing also becomes hook based as opposed to a simple plain old function based. The current t from useTranslations() seems to work when passed around (with some TS type annoyance), but it doesn't do any extraction so that was not an issue.

[bennajah]

Could you make locales accept a typed Locale? I'm getting a TypeScript error as shown in the screenshot below.
It’s not ideal to hardcode locales here since I’ve defined a reusable locales constant in i18n/config.ts

[amannn]

@bennajah This should be fixed in next-intl@4.5.2!

[bmichotte]

We use next-intl on all our websites with a dashboard that allows our customers to directly modify translations if they wish.

Our workflow is as follows: we load the translations from the JSON, then we retrieve what comes from the database.

We merge everything and send it.

    const json = (await import(`../../messages/${locale}.json`)).default
    const flattened = flatten(json) as Record<string, string>

    const url = new URL(`${publicEnv.NEXT_PUBLIC_BASE_URL}/api/i18n`)
    url.searchParams.set('locale', locale)
    const data = await fetch(url.toString())
        .then(res => res.json())
        .catch(() => ({}))

    const messages = {
        ...flattened,
        ...data,
    }

    return {
        locale,
        messages: {
            ...(unflatten(messages) as Record<string, unknown>),
        },
    }

With the system as developed here, our version is no longer possible because the keys change. However, if the keys do not change, then we can use the feature.

Is it possible that the keys are the text as encoded?

Something like :

const t = useExtracted('namespace')

return <span>{t('Hello Github')}</span>

conversion :

{
  "namespace": {
      "Hello Github": "Hello Github"
   }
}

which would allow us to change the value in database while keeping the key ?

Edit: Looks like I'm not the only one wanting this feature :D #2036 (comment)

[amannn]

Nice! I‘ve implemented a .po parser for next-intl while working on the feature since I didn’t find the existing ones to be that good. I‘m planning to open-source it soon as a standalone library in case that’s helpful to you!

[amannn]

@bmichotte It's available here now: po-parser.

The next version of next-intl will depend on it and removes the internal implementation.

[bmichotte]

@amannn that's awesome.

I like that :)

Would you mind adding the original message as a comment on the .po files ?

Let's say

en.po

#: src/app/[locale]/(web)/_components/sidebar.tsx
msgctxt "Menu"
msgid "ATDyLP"
msgstr "New chat"

fr.po

#: src/app/[locale]/(web)/_components/sidebar.tsx
#| New chat
msgctxt "Menu"
msgid "ATDyLP"
msgstr ""

That would help when reviewing the files "manually"

[amannn]

Nice!

Re original message: I think there should be a reusable community adapter for this once custom formatters are supported: #2036 (reply in thread)

[amannn]

@bmichotte po-parser@1.0.2 is out now and next-intl depends on it (ref).

You might want to bump your dependency as well to deduplicate the transitive dependency of next-intl! :)

[bennajah]

When merge default messages with untranslated messages still show empty String

[amannn]

Please see #2036 (comment)

[bennajah]

getting this error in monorepo when using

import { getExtracted } from "@repo/i18n/server";

export default async function Page() {
  const t = await getExtracted();
  return (
    <h1>{t("title")}</h1>
  );
}

./apps/web/app/[locale]/page.tsx

Error evaluating Node.js code
ResolveMessage: Cannot find module 'next-intl/extractor/extractionLoader' from 'C:\Users\benna\dev\my-app\apps\web\.next\dev\build\chunks\[turbopack]_runtime.js'

[amannn]

Any chance you could share a small reproduction? You could start with https://github.com/amannn/next-intl-example-extracted and turn it into a monorepo that illustrates your use case.

[bennajah]

Any chance you could share a small reproduction? You could start with https://github.com/amannn/next-intl-example-extracted and turn it into a monorepo that illustrates your use case.

https://github.com/bennajah/next-intl-monorepo

[amannn]

I don't know, in your example I get errors about Bun not supporting source maps:

But other than that, I just now see that you've wrapped getExtracted into another library. That must not be done, only imports from next-intl are considered.

I'll provide docs about this and more generally also monorepos in the future (see also).

[bennajah]

@repo/i18n/server is a direct mirror of next-intl/server.
So the import is correct

You can see the implementation here:
https://github.com/bennajah/next-intl-monorepo/blob/main/packages%2Fi18n%2Fsrc%2Fserver.ts

[amannn]

While the feature by itself is orthogonal to useExtracted, people who are following along here might be interested in the latest release of next-intl@4.8: Ahead-of-time compilation of messages.

It only requires adding a single precompile: true flag for users of useExtracted, so maybe you're interested in giving it a go!

[bennajah]

How we can use Extracted messages for react-email instead createTranslator API

https://react.email/docs/guides/internationalization/next-intl#3-update-the-email-template

[bennajah]

in my next.js app, I’m using the useExtracted API.
in my react-email templates, i’m using the createTranslator API (works in react-email) and manually adding keys to the messages JSON files.

however, when I start the dev server, all the manually added keys for React Email are automatically removed.

[amannn]

You need to move your manual keys to a separate folder (e.g. a nested one like ./messages/email).

[bennajah]

You need to move your manual keys to a separate folder (e.g. a nested one like ./messages/email).

This works correctly when using a subfolder, but autocompletion and type safety are lost when using createTranslator.

I’m wrapping createTranslator in a helper function to infer types for email-specific messages, but I’m not sure whether this is the correct or recommended approach:

import {
  createTranslator,
  type Locale,
  type NamespaceKeys,
  type NestedKeyOf,
} from "next-intl";
import type defaultMessages from "../messages/emails/en.json";

export async function getTranslations<
  const Messages extends typeof defaultMessages = typeof defaultMessages,
  const Namespace extends NamespaceKeys<
    Messages,
    NestedKeyOf<Messages>
  > = never,
>({ locale, namespace }: { locale: Locale; namespace?: Namespace }) {
  const messages = (await import(`../messages/emails/${locale}.json`)).default;

  return createTranslator<Messages, Namespace>({
    messages,
    locale,
    namespace,
  });
}

[amannn]

This works for me:

I'd recommend not wrapping createTranslator when in doubt.

(let's try to leave this thread on topic—useExtracted—, general TypeScript questions might be better suited for another thread)

[bennajah]

This works for me:

I'd recommend not wrapping createTranslator when in doubt.

(let's try to leave this thread on topic—useExtracted—, general TypeScript questions might be better suited for another thread)

And what about namespace ?

[amannn]

A question from @jokull:

Has anyone made a codemod to migrate to useExtracted?

I'd be curious too for those who have migrated. How did you do it? Was there something that was challenging?

/cc @ceolinwill @kieranm

[kieranm]

We used Claude Code!

[jokull]

I guess I'll use claude code --- to make a codemod 😎

[ceolinwill]

I can't recall. My project was very early on, so it didn't have many things to migrate. I don't remember if I did it manually or if I used LLMs. But I didn't write a codemod.

[amannn]

Nice! If you feel like sharing what you came up with, I'd certainly be interested!

[stefanprobst]

just to confirm: message extraction runs on next dev and next build, but not on next typegen - correct?

[amannn]

Yep, correct! (I'd argue it's not really "typegen")

For edge cases, you can invoke it manually.

[LouisCuvelier]

@amannn Quick question about the extraction lifecycle:
Does next dev / next build perform a full re-scan and re-generation of the translation file every time, or does it work incrementally (only updating changed/new entries)?

I'm asking because I'm running into an issue with the .po format. When I get rebase conflicts on the auto-generated .po file, I resolve them arbitrarily (since it's auto-generated anyway). But after that, I sometimes end up with missing translation errors — and the only way to fix them is to manually edit the file to trigger a re-generation.

I would have expected next build in CI to catch this and regenerate the file correctly, but it doesn't seem to.
Is this the expected behavior, or am I missing something?

[LouisCuvelier]

Thanks for the insight! Though in my case, I don't really need a frozen flag — I actually want the build to extract and use the translations on the fly, even if they're not committed.

My expectation is that next build should extract the translations and use them in the same build, so that production is always up to date regardless of the state of the .po files in the repo. But it seems like the freshly extracted messages aren't being picked up during the build — is that a known limitation, or could it be a timing issue?

[amannn]

I actually want the build to extract and use the translations on the fly, even if they're not committed.

But what about your target locales then? Don't you want to translate all your messages before your app ships to production?

My expectation is that next build should extract the translations and use them in the same build

Got it, I see what you mean! Yeah, this is indeed not supported currently. I'm currently working on #1 and as part of that noticed some potential refactoring for useExtracted that might fit in nicely. I have to evaluate in more detail, but it might unlock this behavior. I made a note of this.

For the time being, you can extract messages manually before running the build—then you're on the safe side.

But my question from above still stands: I'd expect for a production build that all your locales are properly translated. Can you elaborate why this is not relevant in your case?

[LouisCuvelier]

Good point. Right now I'm only working with a single locale, so target locales aren't a concern yet. But I understand that for a multi-locale setup, you'd definitely want everything translated before shipping.

In the meantime, I'll go with the manual extraction approach before the build. On that note, would it make sense to have a dedicated CLI command like next-intl extract? This would be especially useful in the scenario I described above (when AI agents edit code without running next dev). It would make it easy to integrate into CI pipelines as a step before next build, or even as a git hook (e.g. pre-commit) to ensure translations stay in sync regardless of the developer's workflow.

Thanks for the help! Keep pushing 💪

[amannn]

would it make sense to have a dedicated CLI command like next-intl extract?

I've considered it, but one question that this brings up is how config can be supplied. You don't want to repeat all config you currently have in your next.config.ts as CLI args. That brings up the question if a config file like next-intl.config.ts would be necessary, but I think everyone already has enough config files lying around in your root. The only way around would be if next-intl extract would read your Next.js config, but that could have unforeseen consequences (e.g. @nx/next/plugin does so, but has caused a bug for next-intl recently due to this: #2245)

The benefit of the Node.js API is that you can export and reuse config as necessary—that's why I currently prefer it.

For now, I think agents can work best with useExtracted if they either act while next dev is running or when next build runs after work is complete (which I already observe frequently, for agents wanting to validate their work). So I'm not sure if a CLI would complicate things here unnecessarily …

[LouisCuvelier]

Makes sense, thanks for the detailed explanation! I went ahead and created a Node.js script that extracts messages for all apps in our Turborepo monorepo, and integrated it as a pre-commit git hook. That way, translations are always up to date regardless of whether next dev was running or not — which solves the AI agent workflow issue nicely.
Thanks again for the help and the great work on useExtracted!

[stefanprobst]

should the turbopack loader be able to handle .po files imported from a monorepo package?

i.e. i have a ui package which has

"exports": {
  "./i18n/en": "./messages/en.po"
}

and in getRequestconfig():

// local .po file, works
const { default: messages } = await import("@/messages/en.po");
// import from monorepo package, does not work
const { default: fromPo } = await import("@repo/ui/i18n/en");

see https://github.com/stefanprobst/issue-next-i18n

error message:

Unknown module type
This module doesn't have an associated type. Use a known file extension, or register a loader for it.

[amannn]

Thanks for bringing this up, there are currently some docs missing for this (and potentially also a feature).

The core question is whether your @repo/ui package is consumed by multiple apps.

---

If it isn't, then this is pretty straightforward: You can configure srcPath: ['./src', '../../packages/ui'].

In this case, you don't need any messages in ui, and the extractor will put them alongside your app messages. A namespace like useExtracted('ui') might be helpful to provide some structure here (but this is optional).

---

If the messages are indeed shared among multiple apps, then this is a bit trickier. Here, you don't want to extract the messages to the consumer but ship them along with the code.

Using unstable_extractMessages for the one-off extraction is the right pick here. In case of .json, you could already use them as-is, but for .po there's more work necessary.

You could use po-parser to process the file and produce a .json build artifact that your main application can read.

The background is that messages.path: "./messages" defines the exclusive locations where the loader will be used to read messages.

But I know that it would be handy to allow the loader to run on 3rd party messages as well, allowing you to skip the step with building a .json artifact. I have this on my list to evaluate, so hopefully I can provide better support for this!

[stefanprobst]

produce a .json build artifact that your main application can read.

problem is that the dist/ folder of the compiled ui package will still reference the original messages, not the extracted keys, i.e. t("Hello") not t("mnbvcx").

[amannn]

I guess you could use transpilePackages for this. I'll likely create a monorepo example to explore this use case in depth, I'll leave a note here once I have more!

EDIT: #2036 (comment)

[fo-fo]

Any chance the default POCodec could be added to the package exports, to make it available for importing into a custom codec for extension/customization? I'm thinking about removing the line numbers, but I'd prefer not to have to have a copy of POCodec.tsx sitting around in my repo.

[LouisCuvelier]

We're running into the same kind of issue, but I haven't been able to reproduce it reliably.

In our case, only one string keeps moving up and down in the .po file (similar to the example above).

The only potential cause I can think of is that we have a script that manually extracts messages, running as a pre-commit hook. I'm wondering if the manual extraction function and the automatic one triggered by next dev / next build might not produce the same output ?

import { createRequire } from "node:module";
import path from "node:path";

const APPS = ["..."]; // Omitted

const config = {
  sourceLocale: "fr",
  messages: {
    path: "./src/shared/i18n/translations",
    format: "po",
    locales: "infer",
  },
};

const rootDir = path.resolve(import.meta.dirname, "..");

for (const app of APPS) {
  const appDir = path.resolve(rootDir, "apps", app);
  process.chdir(appDir);

  const require = createRequire(path.join(appDir, "package.json"));
  const { unstable_extractMessages } = require("next-intl/extractor");

  await unstable_extractMessages({ ...config, srcPath: "./src" });
  console.log(`✔ ${app}: messages extracted`);
}

[amannn]

Hmm, no—the extraction should be the same. Can you pinpoint in which situation the string moves? And any chance you could share more details, e.g. an (anonymized) messages catalog that contains file references, so I could build up a project for stress testing? Happily also in private if that works better for you.

[anthlasserre]

@LouisCuvelier — picking this up. Yes, the standalone script and next dev / next build can produce different output, and I think I found the root cause. Here's the trace through next-intl@4.9.2.

Where it happens

dist/.../extractor/utils.js:

function getSortedMessages(messages) {
  return messages.toSorted((a, b) => {
    const refA = a.references?.[0];
    const refB = b.references?.[0];
    if (!refA || !refB) return 0;            // (1) ties when refs are missing
    return compareReferences(refA, refB);    // (2) ties on same path + line
  });
}

Both (1) and (2) can return 0, and Array.prototype.toSorted is stable, so ties fall back to insertion order in messagesById. That insertion order comes from extractor/catalog/CatalogManager.js — which builds the Map from a concurrent Promise.all(...) over SourceFileScanner.walkSourceFiles, which uses fs.readdir. fs.readdir does not guarantee a stable ordering, so the insertion order varies across runs/machines.

Why the two paths diverge

The Map insertion order is fed by different processes in each path:

Path	Insertion order driver
unstable_extractMessages (script)	fs.readdir + concurrent Promise.all scan
next dev	Chronological SourceFileWatcher events as files are edited
next build	Concurrent scan at build time (same shape as script, different process)

So even on identical source code, three different "first encountered" orders are possible. For any two messages that tie on references[0], those three orders can each produce a different .po.

Minimal repro from a real codebase

Two t(...) calls in the same JSX expression, both extracted at the same line:

#: src/features/.../my-file.tsx:184
msgid "SXOans"
msgstr "Not configured"

#: src/features/.../my-file.tsx:184
msgid "ukftTp"
msgstr "Configured"

references[0] is identical → comparator returns 0 → order flips between runs. Confirmed:

pnpm run extract:messages
cp en.po en.po.run1
pnpm run extract:messages
diff en.po.run1 en.po   # non-empty

Relation to the earlier 4.5.2 / 4.5.6 fix

@ceolinwill reported the symptom upthread and the fix landed under "Stable, environment-agnostic key sorting". That made the comparator locale-independent (localeCompare(.., 'en') in utils.js), which removed one source of cross-machine non-determinism — but it didn't add a tiebreaker, so messages tied on references[0] still flip. @ceolinwill noted "still one edge case where the order changes if a locale has missing translations" — same root cause: (1) returns 0 for missing refs.

Proposed fix (3 lines in getSortedMessages)

function getSortedMessages(messages) {
  return messages.toSorted((a, b) => {
    const refA = a.references?.[0];
    const refB = b.references?.[0];
    if (refA && refB) {
      const c = compareReferences(refA, refB);
      if (c !== 0) return c;
    }
    if (refA) {
        return 1;
    }
    if (refB) {
        return -1;
    }
    return localeCompare(a.id, b.id);
  });
}

id is already deterministic across runs (it's the hash of msgid + description), so this gives a fully stable order with a tiny one-time canonicalization diff for existing repos. No API change.

Happy to send a PR if useful — let me know.

Our current workaround

Until this lands, we post-process each .po after unstable_extractMessages in our pre-commit script with the same comparator (using po-parser, which is already a transitive dep). ~25 lines, idempotent across consecutive runs. It only fixes committed state — next dev can still leave non-canonical output in the working tree — but every commit re-canonicalizes via the pre-commit hook, so PRs stay clean.

[amannn]

Hey, thanks a lot for digging into this!

One thing to add: Also next dev starts with a full project scan, it only additionally captures changes that are discovered.

But yes, if you'd be interested in sending a PR, I'd happily have a look!

There's a new e2e setup at https://github.com/amannn/next-intl/tree/main/e2e which could ideally be used for demonstrating the issue and then proposing a fix.

[anthlasserre]

Thanks for the clarification on next dev doing a full scan first — that simplifies the picture. Since all three paths (standalone script, dev, build) go through the same getSortedMessages, fixing the comparator there fixes them all.

Opened the PR: #2315

Kept the change minimal — just the localeCompare(messageA.id, messageB.id) tiebreaker, no behaviour change for messages in mixed reference states. Added a regression test in e2e/extracted-po per your suggestion, plus updated the unit tests in extractor/utils.test.tsx. One inline snapshot in ExtractionCompiler.test.tsx > po format > removes flags when externally deleted needed reordering because it produces 5 messages all at the same source line — pure reorder, no content change.

One caveat I called out in the PR: the e2e test verifies the outcome (catalog matches id-sort) rather than causality, since msgids are hashes of source strings and could happen to coincide with insertion order. The unit tests cover the regression directly with controlled input.

Happy to iterate on anything you'd like changed.

[keyboy21]

@amannn Bug: extractionLoader strips trailing comma from TSX generic arrow functions**

Version: next-intl 4.8.0, Next.js 16.2.1

Repro: https://github.com/keyboy21/next-intl-bug-repro-app-router

Error:

⨯ ./src/app/[locale]/(app)/page.tsx
Unexpected token. Did you mean `{'>'}` or `>`?

Generated code of loaders [next-intl/extractor/extractionLoader]:
const identity = <T>(value: T): T =>value;
                                   ^

Root cause:

When experimental.extract is enabled, extractionLoader transforms .tsx source files. In doing so, it strips the trailing comma from generic arrow functions:

// Source (valid .tsx)
const identity = <T,>(value: T): T => value;

// After extractionLoader (broken — <T> is parsed as JSX)
const identity = <T>(value: T): T => value;

In .tsx files, the trailing comma in <T,> is the standard TypeScript disambiguation syntax to tell the parser it's a generic, not a JSX opening tag. Removing it causes a parse error.

Minimal repro (page.tsx):

import { getExtracted } from "next-intl/server";

const identity = <T,>(value: T): T => value; // ← extractionLoader breaks this

export default async function IndexPage() {
  const t = await getExtracted();
  return <div>{t("hello")} {identity("world")}</div>;
}

[amannn]

Thanks for the report, I'll have a look!

[amannn]

Hmm, it seems like the SWC parser somehow removes the trailing comma without a trace. Maybe you could use <T extends unknown> as a workaround? I couldn't find a great fix for this yet, maybe this needs better support upstream in SWC …

[keyboy21]

Yeah, I already do this.

[sezze]

Hi, I'm thinking of adopting this workflow:

1. Developers use useExtracted in code, but automatic extraction is turned off
2. The PRs get merged without any added localization, po files are untouched, this makes the PR very readable
3. On a frequent basis, a GitHub action runs extraction, and checks if there is a diff
4. If yes, make a new automatic PR, and do an initial run of AI localization, which can be checked in the PR

If we were to support say 30 languages, then small PRs that touch localization would be huge, this workflow would improve it from the developer's and reviewer's point of view. The reason I am sending this here, is that I want to check in if this is a workflow that aligns with next-intl and useExtracted, I wouldn't want to fight the desired workflow.

This workflow would need the introduction of a way to prevent automatic extraction during next dev, and require an explicit command to be run to do it. If this is introduced, then this workflow might work.

I made a PR for this, feel free to merge, throw away, or change however you'd like: #2292

[sezze]

To add to this, I sometimes have devs reporting conflicts when pulling new changes, when no localization has been touched. I suspect it happens if next dev is running, and happens to run extraction on an intermediate state in the middle of the pull. I have not confirmed this but can't think of other reasons.

[ellisio]

@sezze In this scenario, have you thought about letting your defaultLocale be the only .po in your messages/ folder? Then, have your setup pull other locales from, say, CDN? You can publish all the locales to that CDN using your workflow, still.

[amannn]

Yep, or you could configure locales: ['en'] in your Next.js config (instead of e.g. infer). This would cause translations to only be extracted to your default locale.

There's one missing piece though: In case you use .po files, you still want to transform the .po catalog into JSON when loading it into your app. This is also needed for certain monorepo setups and something I have on my list to look into.

In case you use .json catalogs, then I think the current feature set of useExtracted should already work for you.

EDIT: #2036 (comment)

[zigang93]

did anyone facing Hydration failed at latest nextjs 16.2.1? if using 16.1.7 is fine.

Uncaught Error: Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client. This can happen if a SSR-ed Client Component used:

- A server/client branch `if (typeof window !== 'undefined')`.
- Variable input such as `Date.now()` or `Math.random()` which changes each time it's called.
- Date formatting in a user's locale which doesn't match the server.
- External changing data without sending a snapshot of it along with the HTML.
- Invalid HTML tag nesting.

It can also happen if the client has a browser extension installed which messes with the HTML before React loaded.

https://react.dev/link/hydration-mismatch

  ...
    <div className="`gap-y-3 f...">
      <CompanyLogo>
      <FormProvider control={{...}} subscribe={function subscribe} trigger={function trigger} ...>
        <form onSubmit={function} className="min-w-62.5...">
          <FormField control={{...}} name="username" render={function render}>
            <Controller control={{...}} name="username" render={function render}>
              <FormItem>
                <div data-slot="form-item" className="grid gap-2">
                  <FormLabel htmlFor="username">
                    <Label data-slot="form-label" data-error={false} className="data-[erro..." htmlFor="username">
                      <Label data-slot="form-label" className="flex items..." data-error={false} htmlFor="username">
                        <Primitive.label data-slot="form-label" className="flex items..." data-error={false} ...>
                          <label
                            data-slot="form-label"
                            className="flex items-center gap-2 text-sm leading-none font-medium select-none group-data..."
                            data-error={false}
                            htmlFor="username"
                            onMouseDown={function onMouseDown}
                            ref={null}
                          >
+                           Username~
-                           Username
                  ...
          ...

some Unusual log happend:

⚠ Fast Refresh had to perform a full reload when ./apps/micron/locales/en.po.js changed. Read more: https://nextjs.org/docs/messages/fast-refresh-reload
⚠ Fast Refresh had to perform a full reload when ./apps/micron/locales/en.po.js changed. Read more: https://nextjs.org/docs/messages/fast-refresh-reload
 GET /login 200 in 376ms (next.js: 29ms, proxy.ts: 81ms, application-code: 265ms)
 GET /login 200 in 186ms (next.js: 97ms, proxy.ts: 15ms, application-code: 75ms)
 GET /login 200 in 479ms (next.js: 86ms, proxy.ts: 23ms, application-code: 371ms)
 GET /login 200 in 593ms (next.js: 66ms, proxy.ts: 60ms, application-code: 467ms)
 GET /login 200 in 535ms (next.js: 122ms, proxy.ts: 19ms, application-code: 393ms)
 GET /login 200 in 398ms (next.js: 27ms, proxy.ts: 29ms, application-code: 342ms)

[ellisio]

[keyboy21]

See this: #2036 (reply in thread)

Only statically analyzable calls like t('Hello!') are supported, anything dynamic like t(key) will print an error

[ellisio]

Thanks @keyboy21. I meant to edit my comment, not delete. Anyone looking at this in the future, I was referencing passing t around through function arguments, breaking static analysis; which this implementation depends on.

[ceolinwill]

One area that we could have better DX is monorepo support. It would be great if we could have something like this:

• shared package runs one-off extraction into packages/<name>/messages/*.po
• apps can consume multiple message roots, e.g. messages.path: ['./messages', '../../packages/player/messages']
• apps can transform useExtracted in shared package source without also extracting those messages into the app’s own catalog
• no extra webpack/turbopack/custom build config

[amannn]

Yep, I agree—I'll look into this! (related to #2036 (reply in thread))

EDIT: #2036 (comment)

[ellisio]

I think there might be a bug related to Next's telemetry (detached-flush), and it's exposing some kind of non-deterministic saving of files. I've filed a bug with Next here around disabling this behavior if telemetry is disabled. No idea if it will ever get merged in.

Regardless, with all the agentic workflows, we're seeing zombie processes popping up when next dev is ran, then killed improperly (invalid shutdown sequence). This results in tons of these zombies hanging out:

37651     1 08-09:17:38 /Users/andrew/.nvm/versions/node/v24.15.0/bin/node /Users/andrew/Developer/next-intl-demo/node_modules/.pnpm/next@16.2.4_babel-plugin-react-compiler@1.0.0_react-dom@19.2.5_react@19.2.5__react@19.2.5/node_modules/next/dist/telemetry/detached-flush.js dev /Users/andrew/Developer/next-intl-demo _events_6343.json

This is introducing behavior that is exposed when you switch branches with Git. The below will result in un-staged file:

1. git checkout main; git pull; git checkout -b feature/test
2. Make changes that result in messages/en.json changes. Commit.
3. git checkout main
4. Observe en.json being modified.

This happens because those zombie processes are still watching files and running next-intl, even though we've technically killed off next dev at this point. If I get into the scenario where those 4 steps above can be consistently reproduced, killing those detached-flush.js PIDs resolve the issue.

So, two major things here:

1. Why is next-intl running inside of that detached-flush.js fork?
2. Why is next-intl, in this scenario, shuffling the order of messsages/en.json keys (non-deterministic)?

I wish I could provide an actual repository publicly that gets into this bad behavior, but the biggest offender is my company's project, so I can't give you access. I've attempted to reproduce this in a new fresh NextJS repo, but... of course I'm not able to.

I don't want to throw agentic stuff at you, but I've been debugging this for weeks and finally narrowed it down to this detached-flush.js stuff, and this is what Claude gave me when I explained the scenario to it, so I have no idea if this is helpful.

Longer-term, this is worth filing — either against next-intl (its plugin shouldn't keep the loop alive when imported purely for config introspection) or against Next (telemetry flush shouldn't fully evaluate user plugins). A process.exit() after the POST in detached-flush.js would also defend against it. If you want a workaround in the meantime, gating withNextIntl(...) on process.env.NEXT_TELEMETRY_DISABLED !== '1' won't help (the flush runs regardless of telemetry being on), but checking process.argv[1].includes('detached-flush') and short-circuiting in your next.config.ts would.

We're testing with the following next.config.ts change for now. Hopefully this solves our headache for a little while until we can fully understand what is going on, and how to fix this:

const isTelemetryFlush = process.argv[1]?.includes("detached-flush") ?? false;

const withNextIntl = isTelemetryFlush
  ? <T>(config: T): T => config
  : createNextIntlPlugin({
      experimental: {
        srcPath: "./src",
        extract: { sourceLocale: "en" },
        messages: {
          path: "./messages",
          format: "json",
          locales: "infer",
          precompile: true,
        },
      },
    });

[ellisio]

@amannn We bumped versions today, and the detached-flush issue has completely vanished. We don't even have zombie processes showing up. So, I'm wondering if the zombies we were seeing were a result of next-intl itself? I have no foundation to make that a declarative statement, just a hunch.

However, we're still seeing some non-determistic issues when we fire up next dev on fresh branches off main. The JSON files will flip things around like this:

-  "UVkKe5": "Sending code...",
   "nx5jYc": "Send sign-in code",
+  "UVkKe5": "Sending code...",

Edit: I've opened PR #2320. The core lines I changed in the getSortedMessages() method have a PNPM patch on our end. I'm going to run this patch for a few days next week to see if the weird behavior totally stops. Let me know if you can think of anything else that might be a cause. I'm willing to guinea pig test anything you need around this.

Here's the patch I have:

diff --git a/dist/cjs/development/plugin-0S9vVrVM.cjs b/dist/cjs/development/plugin-0S9vVrVM.cjs
index d02f53df33e5011b1bf8cb63393ba54b9540a1fc..45b4200946681eac7eb47b20595491788d3449d0 100644
--- a/dist/cjs/development/plugin-0S9vVrVM.cjs
+++ b/dist/cjs/development/plugin-0S9vVrVM.cjs
@@ -370,13 +370,23 @@ function getSortedMessages(messages) {
     const refA = messageA.references?.[0];
     const refB = messageB.references?.[0];
 
-    // No references: preserve original (extraction) order
-    if (!refA || !refB) return 0;
-
-    // Sort by path, then line. Same path+line: preserve original order
-    return compareReferences(refA, refB);
+    // Group reference-less messages after referenced ones; tiebreak by id so
+    // the comparator is a total order (transitive) and the result is
+    // independent of input order. The previous `return 0` for the mixed case
+    // produced non-transitive comparisons, which made catalog output depend
+    // on parallel extraction timing and caused spurious diffs.
+    if (!refA && !refB) return compareIds(messageA.id, messageB.id);
+    if (!refA) return 1;
+    if (!refB) return -1;
+
+    const cmp = compareReferences(refA, refB);
+    if (cmp !== 0) return cmp;
+    return compareIds(messageA.id, messageB.id);
   });
 }
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 function localeCompare(a, b) {
   return a.localeCompare(b, 'en');
 }
diff --git a/dist/esm/development/extractor/utils.js b/dist/esm/development/extractor/utils.js
index 7dde2053cf98cf864f59494f13c3fa70baa93eab..82cbf03777a010515ce11039df8b73237da8b766 100644
--- a/dist/esm/development/extractor/utils.js
+++ b/dist/esm/development/extractor/utils.js
@@ -33,13 +33,23 @@ function getSortedMessages(messages) {
     const refA = messageA.references?.[0];
     const refB = messageB.references?.[0];
 
-    // No references: preserve original (extraction) order
-    if (!refA || !refB) return 0;
+    // Group reference-less messages after referenced ones; tiebreak by id so
+    // the comparator is a total order (transitive) and the result is
+    // independent of input order. The previous `return 0` for the mixed case
+    // produced non-transitive comparisons, which made catalog output depend
+    // on parallel extraction timing and caused spurious diffs.
+    if (!refA && !refB) return compareIds(messageA.id, messageB.id);
+    if (!refA) return 1;
+    if (!refB) return -1;
 
-    // Sort by path, then line. Same path+line: preserve original order
-    return compareReferences(refA, refB);
+    const cmp = compareReferences(refA, refB);
+    if (cmp !== 0) return cmp;
+    return compareIds(messageA.id, messageB.id);
   });
 }
+function compareIds(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
 function localeCompare(a, b) {
   return a.localeCompare(b, 'en');
 }

[amannn]

So, I'm wondering if the zombies we were seeing were a result of next-intl itself? I have no foundation to make that a declarative statement, just a hunch.

It could be, maybe the accidentally triggered watcher caused the process to stick around. But good to hear that it's gone now!

Here's the patch I have

Thanks for looking into this! My assumption would actually be that there is no such thing as "reference-less messages", but maybe I'm overlooking something. I did some refactoring around references in #2318, I'll investigate again there if I can find something suspicious based on your finding. I should at least be able to add error-handling for this case.

[ellisio]

@amannn Excellent! We are working through getting our main branch all cleaned up and stable this morning. The dev team is going to be branching off our stabilized main, which has the patch above. We'll know by EOD if this helped, or not. 🤞 Report back in a bit!

[ellisio]

@amannn Even with that patch applied we're still seeing shuffling of JSON key orders. Dang it. We'll keep an eye out for your release so we can bump and test your changes. 🤞

[amannn]

Sounds good, thanks!

@anthlasserre discovered a case that led to indeterministic sorting, I'm addressing it here: #2324. Maybe that could be the fix for the issue you're seeing!

[amannn]

🌐 next-intl 4.12 is out with useExtracted improvements!

• Improved monorepo support
• Stacked .po descriptions
• Path-only references by default (line numbers require a custom codec now)
• Deferred one-off extraction
• Another message ordering fix

⚠️ A small config change is required to upgrade, please see #2316.

[bmichotte]

Thank you so much for the line numbers !

[ellisio]

Full day of dev, no shuffling of messages/*.json keys. Nice work folks! 🥳

[amannn]

🌐 next-intl 4.13 is out with a useExtracted fix!

Auto-generated useExtracted message keys now use URL-safe base64 (-_) instead of standard base64 (+/). This fixes an SEO issue with Googlebot that is otherwise hard to work around (see #2250).

⚠️ This requires an update to your existing keys, please point your agent of choice at #2330 to upgrade.