feat(macro): Add arg macro tests, docs and typings

[DeyLak]

Description

This PR resolves part of the discussed changes in https://github.com/lingui/js-lingui/issues/2279. It adds tests, docs and typings for the arg macro that was already available in the babel plugin.

Types of changes

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

Fixes https://github.com/lingui/js-lingui/issues/2279

Checklist

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

[vercel[bot]]

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

Name	Status	Preview	Updated (UTC)
js-lingui	✅ Ready (Inspect)	Visit Preview	Aug 4, 2025 8:55am

[codecov[bot]]

Codecov Report

:x: Patch coverage is 80.00000% with 2 lines in your changes missing coverage. Please review. :white_check_mark: Project coverage is 77.01%. Comparing base (6bb8983) to head (e9f03e1). :warning: Report is 211 commits behind head on main.

Files with missing lines	Patch %	Lines
...ckages/babel-plugin-lingui-macro/src/macroJsAst.ts	80.00%	1 Missing and 1 partial :warning:

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2292      +/-   ##
==========================================
- Coverage   77.05%   77.01%   -0.04%     
==========================================
  Files          84       89       +5     
  Lines        2157     2506     +349     
  Branches      555      651      +96     
==========================================
+ Hits         1662     1930     +268     
- Misses        382      461      +79     
- Partials      113      115       +2     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

:rocket: New features to boost your workflow:

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

[timofei-iatsenko]

Regardless of the original conversation we had, i feel that this PR is still quite a valuable contribution for the library, so would like to move this forward.

The PR itself LGTM

[timofei-iatsenko]

I'd like to do some changes first, than will mark as ready

[timofei-iatsenko]

I added support for named placeholders to the arg macro, to be consistent with other places and added type tests for that.

[timofei-iatsenko]

@andrii-bodnar anything else to be done to merge it?

[andrii-bodnar]

@timofei-iatsenko I was waiting here for https://github.com/lingui/swc-plugin/pull/161, to release them synchronously