feat: Add displayName to useFormatter

[roderickhsiao]

Description

Exposes Intl.DisplayNames through the useFormatter hook as a new singular displayName formatter, consistent with existing formatter APIs while matching the underlying Intl.DisplayNames naming.

Why

Intl.DisplayNames was already wired in the internal formatter cache (createIntlFormatters) but was never surfaced via useFormatter. This PR adds the missing public API and keeps naming/docs aligned.

What changed

• packages/use-intl/src/core/createFormatter.tsx
  • Adds displayName(value, options) and displayName(value, format, options?) overloads.
  • Reuses formatters.getDisplayNames cache-backed instances.
• packages/use-intl/src/core/Formats.tsx
  • Adds displayName?: Record<string, Intl.DisplayNamesOptions> to global formats.
• packages/use-intl/src/core/AppConfig.tsx
  • Adds displayName format-name typing support in FormatNames augmentation.
• packages/use-intl/src/react/useFormatter.test.tsx
  • Adds coverage for region/language/currency formatting, named global formats, and Intl.DisplayNames instance caching.
• Documentation updates:
  • docs/src/pages/docs/usage/display-name.mdx (renamed from display-names.mdx) with singular API examples.
  • docs/src/pages/docs/usage/_meta.tsx route key updated to display-name.
  • docs/src/pages/docs/usage/configuration.mdx and docs/src/pages/docs/workflows/typescript.mdx updated to singular key/API usage.
  • docs/src/pages/docs/environments/runtime-requirements.mdx now explicitly lists Intl.DisplayNames and corresponding polyfill entries.

Test plan

• format.displayName('US', {type: 'region'}) -> "United States"
• format.displayName('en', {type: 'language'}) -> "English"
• format.displayName('USD', {type: 'currency'}) -> "US Dollar"
• Named global format: format.displayName('US', 'region') with formats.displayName.region = {type: 'region'}
• Intl.DisplayNames instances are cached for equivalent options

Verification run

• pnpm --filter use-intl test -- run src/react/useFormatter.test.tsx (pass)
• Docs formatting checked with Prettier on changed docs files

[vercel]

@roderickhsiao is attempting to deploy a commit to the next-intl Team on Vercel.

A member of the Team first needs to authorize it.

[amannn]

Hey @roderickhsiao, thanks a lot for this PR—this looks really great!

There's only one API consideration I'd raise, let me know what you think.

[roderickhsiao]

@amannn thanks for the review, love the work! updated PR.

Cheers

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
next-intl-docs	Ready	Preview, Comment	Apr 28, 2026 6:27pm
next-intl-example-app-router	Ready	Preview, Comment	Apr 28, 2026 6:27pm
next-intl-example-app-router-without-i18n-routing	Ready	Preview, Comment	Apr 28, 2026 6:27pm

[amannn]

Awesome, thanks!

One last thing: CI is failing because size budgets for use-intl and next-intl need to be adjusted.

See .size-limit.ts files in the relevant directories.

Can you have a quick look? I think maintainer edits aren't turned on for this PR.

[roderickhsiao]

Awesome, thanks!

One last thing: CI is failing because size budgets for use-intl and next-intl need to be adjusted.

See .size-limit.ts files in the relevant directories.

Can you have a quick look? I think maintainer edits aren't turned on for this PR.

I got you, one sec

[amannn]

Regarding 597c3e4, I think I'd prefer a sorting in the docs based on how often the APIs are needed (dates and numbers more than display names). Can you revert that part?

In code, I'm fine with either sorting.

[roderickhsiao]

I'll let you decide, I think its in general the usage is kind of bias (if number is more than dates?) but I also get your point

[amannn]

Yeah, I honestly don't know if date or number formatting is more popular (would guess for dates), but having these come first makes sense IMO.

Thanks a lot!

[amannn]

One minor thing I noticed on a final look

[amannn]

Awesome, thanks! 🙌

[roderickhsiao]

Thank you for the patient review :)