chore: deprecate Intl wrapper helpers and document removal by yslpn · Pull Request #2386 · lingui/js-lingui

yslpn · 2025-12-16T22:43:57Z

Description

Deprecate Lingui’s Intl wrappers (i18n.date/number plus the shared date/time/number helpers) ahead of removal, and add documentation callouts to direct users to native Intl.DateTimeFormat/Intl.NumberFormat. Related: #2265.

Open question for @timofei-iatsenko: do we also want a short blog for this deprecation, and is it OK to plan removal in the next major given the ESM-only focus discussed in #2363? Or it would be better to change the deprecated message.

Background

Initially, Lingui aimed to be a Swiss Army knife for localization, trying to take on as much as possible: from DX to performance optimization. We strived to create convenient formatting wrappers with built-in memoization, normalization, and so on. Now we have functions like i18n.date and i18n.number. But this prevents us from moving forward, and we need to abandon them.

Problems

Creating such wrappers around native APIs leads to the following problems:

This is additional code that needs to be supported and maintained. The library does too much. We need to do less, but do it well. Lingui JS should focus on message extraction and working with catalogs. Formatting dates, numbers, and so on is the job of the Intl API.

These wrappers increase bundle size. Not all users use them. For example, there may be applications where date formatting doesn't depend on locale and is configured manually by the user. Tree-shaking doesn't work here because these are class methods.

We can't create wrappers for all Intl methods—there are too many of them https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl. This leads to poor DX when it's unclear what's in the library and what's not. This is exactly what prompted me to create an issue when I couldn't find how to use Intl.NumberFormat in Lingui.

Plan

In a minor release, we're publishing a blog post, updating documentation, and adding deprecated warnings for methods via JSDoc comments.

In one of the major releases, we will remove the methods, but before that, we'll give enough time for users to prepare their code.

Migrating to native Intl

The migration principle is simple: we need to replace the use of i18n.date and i18n.number methods with direct use of Intl.DateTimeFormat and Intl.NumberFormat respectively.

i18n.date(date, options) => new Intl.DateTimeFormat(i18n.locale, options).format(date);
i18n.number(n, options) => new Intl.NumberFormat(i18n.locale, options).format(n);

Example without React:

import type { I18n } from "@lingui/core";

const dateOptions = { dateStyle: "medium" } as const;
const currencyOptions = {
  style: "currency",
  currency: "EUR",
} as const;

export function formatOrderSummary(i18n: I18n, date: Date, total: number) {
  const dateFormatter = new Intl.DateTimeFormat(i18n.locale, dateOptions);
  const numberFormatter = new Intl.NumberFormat(i18n.locale, currencyOptions);

  // "Jan 18, 2026 - €1,234.56"
  return `${dateFormatter.format(date)} - ${numberFormatter.format(total)}`;
}

In React you have to use useMemo to memoize formatters and react to locale changes:

import { useLingui } from "@lingui/react";
import { useMemo } from "react";

const dateOptions = { dateStyle: "medium" } as const;
const priceOptions = {
  style: "currency",
  currency: "USD",
  minimumFractionDigits: 2,
} as const;

function PriceLine({ date, total }: { date: Date; total: number }) {
  const { i18n } = useLingui();

  const dateFormatter = useMemo(
    () => new Intl.DateTimeFormat(i18n.locale, dateOptions),
    [i18n.locale]
  );
  const numberFormatter = useMemo(
    () => new Intl.NumberFormat(i18n.locale, priceOptions),
    [i18n.locale]
  );

  return (
    <span>
      {/* "Jan 18, 2026 - $1,234.56" */}
      {dateFormatter.format(date)} - {numberFormatter.format(total)}
    </span>
  );
}

Types of changes

Bugfix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality not to work as expected)
Documentation update
Examples update

Fixes #2265

Checklist

I have read the CONTRIBUTING and CODE_OF_CONDUCT docs
I have added tests that prove my fix is effective or that my feature works
I have added the necessary documentation (if appropriate)

vercel · 2025-12-16T22:44:01Z

@yslpn is attempting to deploy a commit to the Crowdin Team on Vercel.

A member of the Team first needs to authorize it.

codecov · 2025-12-16T22:50:56Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.27%. Comparing base (6bb8983) to head (13c55fc).
⚠️ Report is 256 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2386      +/-   ##
==========================================
+ Coverage   77.05%   81.27%   +4.22%     
==========================================
  Files          84      104      +20     
  Lines        2157     2718     +561     
  Branches      555      724     +169     
==========================================
+ Hits         1662     2209     +547     
+ Misses        382      363      -19     
- Partials      113      146      +33

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

timofei-iatsenko · 2025-12-17T10:24:03Z

Hey @yslpn thanks for the contribution. I'm not sure that developers would have enough time to transition and that will not block adoption ESM only linguijs.

So it would be better to not remove it in the next major version. Blog post would be much apreciated to explain what was the driver for the decision.

Meanwhile, do you think it would be nice to have ready to use react hooks as an alternative? Because users will still have to create them on their own, may be we can create them and make available out of the box?

…ation

yslpn · 2025-12-17T15:20:03Z

Meanwhile, do you think it would be nice to have ready to use react hooks as an alternative? Because users will still have to create them on their own, may be we can create them and make available out of the box?

If we ship ready-made React hooks for date/number formatting, people will soon want the same helpers outside React, and we end up back where we were: maintaining wrappers around every Intl method. I'd prefer to keep recommending native Intl.* directly. If someone needs helpers, they can create their own functions or hooks.

Does that sound good to you?

Blog post would be much apreciated to explain what was the driver for the decision.

I also drafted a blog post to explain the deprecation and migration; would love your take on it. The social image in the post was generated via AI (Nano Banana by Gemini).

timofei-iatsenko · 2026-01-19T10:36:14Z

I’ll be honest with you: this PR has been sitting around because the blog post feels very LLM-ish, and I don’t really want to merge something like that. I also don’t have enough energy to rewrite it myself, so I’ve been kind of dodging this PR.

Could you rewrite it in a more human way — how you would explain what changed and why — without going into too much detail? Ideally, it should be engaging to read and feel less like it was written by a robot.

yslpn · 2026-01-19T11:34:32Z

I’ll be honest with you: this PR has been sitting around because the blog post feels very LLM-ish, and I don’t really want to merge something like that. I also don’t have enough energy to rewrite it myself, so I’ve been kind of dodging this PR.

Could you rewrite it in a more human way — how you would explain what changed and why — without going into too much detail? Ideally, it should be engaging to read and feel less like it was written by a robot.

Yes, I used LLM when writing it. I'll mark the PR as a draft and rewrite it when I'm ready.

vonovak

I added a few suggestions. We should revisit especiially the "Migrating to native Intl" section.
But thanks for the work!