feat: add ph() and explicit labels for placeholders

[timofei-iatsenko]

Description

Adds a way to give an explicit name for placeholders in the messages. There are two syntaxes supported:

import {t} from "@lingui/core/macro";
t`Hello ${{name: getUsername()}}`

And with explicit ph helper:

import {ph, t} from "@lingui/core/macro";
t`Hello ${ph({name: getUsername()})}`

Shortcut syntax is also supported:

import {t} from "@lingui/core/macro";
const name = "World"
t`Hello ${{name}}`

plural / select / selectOrdinal:

import {t, plural} from "@lingui/core/macro";
t`We have ${plural({count: getDevelopersCount()}, {one: "# developer", "# developers"})}`

In the JSX

import {Trans} from "@lingui/react/macro";

<Trans>Hello {{name: getUsername()}}</Trans>;

import { Plural } from "@lingui/react/macro";

<Plural
  value={{ count: getCount() }}
/>

Note, that Children type for the Trans component was amended to allow passing an object. However, inner elements in the Trans will not allow that, and the only one way to use is a ph() helper macro, which basically a type helper to mitigate this issue.

import {ph} from "@lingui/core/macro";
import {Trans} from "@lingui/react/macro";

// ❌ this will not work, children of `strong` element does not accept an arbitrary object
<Trans>Hello <strong>{{name: getUsername()}}</strong></Trans>; 

// ✅ with a help of `ph()` macro it will work
<Trans>Hello <strong>{ph({name: getUsername()})}</strong></Trans>; 

PS

Actually everything could be covered with ph() helper, but i've found syntax without it much easier to write in day to day routine. So i decided to left both of them. For most of cases just {name: getName()} and for cases where it doesn't work the ph.

The implementation is almost the same, to support both of the methods it's additional 10 lines of code.

Let me know what you think about it.

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 to not work as expected)
• Documentation update
• Examples update

Fixes # (issue)

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]

@timofei-iatsenko is attempting to deploy a commit to the Crowdin Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

size-limit report 📦

Path	Size
./packages/core/dist/index.mjs	3.22 KB (0%)
./packages/detect-locale/dist/index.mjs	722 B (0%)
./packages/react/dist/index.mjs	1.65 KB (0%)
./packages/remote-loader/dist/index.mjs	7.26 KB (0%)

[codecov]

Codecov Report

Attention: Patch coverage is 65.00000% with 7 lines in your changes missing coverage. Please review.

Project coverage is 75.81%. Comparing base (6bb8983) to head (e3ea7d4).
Report is 140 commits behind head on main.

Files with missing lines	Patch %	Lines
...ckages/babel-plugin-lingui-macro/src/macroJsAst.ts	53.33%	3 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2092      +/-   ##
==========================================
- Coverage   77.05%   75.81%   -1.24%     
==========================================
  Files          84       87       +3     
  Lines        2157     2390     +233     
  Branches      555      627      +72     
==========================================
+ Hits         1662     1812     +150     
- Misses        382      459      +77     
- Partials      113      119       +6     

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

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
js-lingui	✅ Ready (Inspect)	Visit Preview	Dec 23, 2024 5:12pm

[timofei-iatsenko]

@andrii-bodnar rebased to main branch

[timofei-iatsenko]

@andrii-bodnar anything here stopping from merging?

[andrii-bodnar]

I would love to play with this feature, but I am pretty busy at the moment :(. Will try to find some time probably next week.

What about the SWC version of this? We have a lot of users who use SWC and it would probably be better to ship such features fully functional.