feat!: use base64 urlsafe alphabet for id

[timofei-iatsenko]

Description

This PR adresses this issue: #2207
SWC PR: lingui/swc-plugin#194

This PR brings url-safe base64 decoding for ids.

Note for migration:

• If Po format and bundlers loaders is used - no manual migration is required.
• If lingui compile command used - You need to recompile your catalogs after updating.
• If some of the formats that explicitly store Lingui IDs is used - A manual migration is required. You’ll need to update the IDs.

The URL-safe variant differs from standard Base64 only by the following transformations:

    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "")

In practice, this means you can migrate existing IDs with a simple search-and-replace in your text editor.

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]

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

Project	Deployment	Actions	Updated (UTC)
js-lingui	Ready	Preview	Feb 8, 2026 11:54am

[github-actions]

size-limit report 📦

Path	Size
packages/core/dist/index.mjs	1.77 KB (0%)
packages/detect-locale/dist/index.mjs	618 B (0%)
packages/react/dist/index.mjs	1.21 KB (0%)

[yslpn]

Thanks for taking this on.

If Po format and bundlers loaders is used - no manual migration is required.

Could this cause migration issues in the isGeneratedId checks used by the translationIO services and format-po? I’m concerned that legacy IDs might be incorrectly treated as explicit IDs.

[timofei-iatsenko]

Should not, because they doesn't store lingui id anywhere, they are produce them from the message every time.