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). This is tricky to implement for next build though, as we're currently in a fire-and-forget mode for async extraction and it's tough to fail the process from there (next build calls process.exit(0), so even beforeExit handlers don't work—only way would be to override process.exit). Workaround: Check git status after next build yourself.
• Could be that some change events are dropped (ref)
• Ensure extraction runs before build (ref)
• addDependency / addContextDependency instead of watcher? Or emit/collect.
• useExtracted auto-generated message keys starting with / cause Google crawler 404 errors #2250
• SWC plugins are "experimental" (see Remove JS-based loader bridge for SWC plugin of useExtracted to further improve transform performance #2187)
• 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?
• Reuse the extraction pipeline for useTranslations?
• 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
• 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

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