Stabilize `useExtracted`

[amannn]

With next-intl@4.5, there's now experimental support for useExtracted.

The next phase will be to collect feedback, fix bugs, potentially incorporate changes and fill in the gaps for missing features and docs.

TODO

• "Frozen" mode? (ref)
• Could be that some change events are dropped (ref)
• Ensure extraction runs before build (ref)
• addDependency / addContextDependency instead of watcher?
• Options for excluding line numbers? (ref, ref)
• useExtracted auto-generated message keys starting with / cause Google crawler 404 errors #2250
• Support calling await getExtracted with Promise.all?
• Docs/demo for monorepos (ref)
  • Not shared messages (transpilePackages: ['@acme/ui'] can be used, but not necessarily)
  • Shared messages (what if consumers build messages themselves after running extraction script? (ref))
• Docs about not touching target locales (but only extract to source catalog)
• Docs about static analyzability (check if errors are thrown)
  • Calls to t (ref, related to above point, ref)
  • No wrapping (ref)
  • We should also mention this for useTranslations. It works, but this has downsides (ref)
  • No passing of t (ref)
  • More docs for array-esque data (ref)
  • Can't use getExtracted() in Promise.all() #2165
• SWC plugins are "experimental" (see Remove JS-based loader bridge for SWC plugin of useExtracted to further improve transform performance #2187)
• Autocomplete with type augmentation, but allow new messages (ref). It doesn't work for .po unfortunately though.
• We should mention in docs that messages are read during build (this might be non-obvious).
• Think more about fallbacks (ref). Should we treat empty messages as errors in next-intl? This would be a minor breaking change. People can guard against this though with t.has.
• Reconsider msgid for .po to be ID or source message (ref 1, ref 2). Should we accept ID-less messages and generate them on demand?
• Ask for more feedback
  • Node.js website team

Future explorations

• How to migrate from hand-crafted keys to autogenerated ones (Codemod? Contributions are welcome)
• A way to migrate catalogs when changing the format
• Tool calls for get all missing translations / translate missing / etc.
• A way to fix source text, i.e. pick a message by key and migrate it to a new message that is synced back into source code (e.g. with an editor, or could we also just watch the source catalog and automatically sync to source?)
• Validation that extracted message for source locale matches source code
• ESLint rule that checks that you're not using dynamic expressions with t
• Provide supplemental descriptions for translations automatically via AI (related: Crowdin Context Harvester)
• Improve/add defaults
  • Detect srcPath automatically (like Tailwind)
  • Also all others could have defaults, but the question remains whether extraction remains opt-in
• Remove JS-based loader bridge for SWC plugin of useExtracted to further improve transform performance #2187
• Support for use-intl (related to ☂️ Umbrella: Support for other frameworks #1863)

---

This list acts as my personal todo list that I want to share for transparency, but please be sure to comment here if you have feedback for the feature:

→ #2036

[zigang93]

@amannn How does the new useExtracted API work with https://github.com/lokalise/i18n-ally?
I’m kind of missing the feature where we’re able to preview all locales or auto-translate directly from the VS Code plugin.

we love the useExtracted API and it improved our DX

[amannn]

@zigang93 In the useExtracted docs for formats you can find links to tools which might be helpful. i18n Ally can still be helpful if you use .json, but for .po you need another tool (e.g. Poedit).

That being said, I'm thinking about providing such a plugin in the future myself with extended support for common workflows with next-intl!

Side note: Let's keep the discussion over in #2036

[kasp416h]

I might just be confused,
but normally when I use translations in SSR, I use getTranslations in the page.tsx and pass the t() function to the server components children.
But when I try this with getExtracted, it does not automatically extract the messages in the server components children? Same with useExtracted.
Maybe its just bad practice how I do it?

[amannn]

The t function can not be passed around, please see also #2036 (comment). I'll have to add docs and error handling for this case, it's still on my list …