Consider renaming of the macro components

[timofei-iatsenko]

Extracted from here

I believe the initial idea for macro was a "subset" of the original params from runtime versions (as original author said). So they signatures originally had to match to each other.

But since then react/js ecosystem shifted towards typescript and quality typings and high type safety become a more valuable than ever. That resulted in changes in lingui, where runtime and macro version got they own typings with different signatures to highlight for developers different usages of macro/runtime versions.

So now we haveTrans from /react and Trans from /react/macro which are different components. This PR will add useLingui from /react/macro in additional to /react. This is indeed confusing. It's also confusing for IDEs, they can automatically add import to incorrect symbol and user may spend hours to understand why it doesn't work as expected.

I think, maybe it's time to change the naming to something more explicit?

Trans / TransM and useLingui / useLinguiM

The Plural, Select and SelectOrdinal don't have runtime counterparts, they are transpiled to Trans, but i believe they should be renamed to follow the same naming convention:

PluralM SelectM and SelectOrdinalM

What do you think? What would be a better name for Macro version? Do you think this is worth the discussion, or it's fine how it is right now?

[andrii-bodnar]

I was thinking about renaming the macro Trans -> trans. These M suffixes don't feel well.

Still don't have a good idea about the useLingui naming.

[timofei-iatsenko]

I saw this particular pattern with some react libs when they transitioned to functional components and created OverlayView and OverlayViewF, Polyline and PolylineF.

I actually OK with current naming, wanted to gather more feedback from people.

[cwhenderson20]

I was thinking about renaming the macro Trans -> trans

Wouldn't this break React Native support? In React Native, all components need to be Capitalized.

[edzis]

I had the same concern initially but now I am leaning towards not changing the naming, but solving that with documentation and tooling.

This may be an overkill but currently I am leaning to explore an approach where we guide user into one of 4 flavors (or worlds) of LinguiJS:

• macro - the preferred way, import everything only from the macros world, with short names
  • thanks to @timofei-iatsenko I recognize that the paths have to stay as is, with /macro suffix for babel-plugin-macros to pick them up
• basic - a fallback way for those who can't use macros and need to rely on ids or MessageDescriptors, with short names
  • there may be a better name than basic
  • we may want to add a path suffix to make it clear that this is a specific world parallel to macro
• mixed - use both approaches in the same project, frequently in the same files, with longer names for clarity
  • expose objects with B and M suffices in imports
  • maybe another path suffix for these
• legacy
  • same paths and props as on v4
  • for those who want to upgrade without changing their code yet or to upgrade it gradually

Based on the chosen flavor we recommend specific apis. Here is what @timofei-iatsenko pointed out for the macro flavor:

/**
 * @see https://discord.com/channels/974702239358783608/1295839293285203968/1296007512390107217
 * In fact you need to use only 3 things:
 * - msg for the messages outside of react context
 * - Trans from react/macro for JSX
 * - useLingui from react/macro in react context for attributes and other places where JSX could not be used.
 */

Based on the chosen flavor we recommend different values for "typescript.preferences.autoImportSpecifierExcludeRegexes" so that intellisense offers just the relevant imports. But user can still import what they want manually.

With this we may cut some of the legacy exports and hook props in the macro and basic flavors.

We may also need to improve the types to help avoid mixing up inputs. For example in the macro-world we may want MessageDescriptor['id'] to be a branded type so that I can not accidentally pass a translatable string in some of the APIs. Similarly in the basic-world we want to help the user validate that the id they are using is in fact a recognized id. And if they know better they should be able to cast any string as MsgID. Same would be valuable also in macro-world for cases where a message is already in the library and we just want to reference it. But the legacy-world may keep the id as just a string. If enforcement inside the lib is too dangerous we may want to keep MsgId extends string but guide users to override it to something specific for their intents - see https://emotion.sh/docs/typescript#define-a-theme. That may be paired with a generating a list of keys in the lingui compile --typescript command.