[macros] Configurable default `context` value generation for macros

[mogelbrod]

Problem Description

My organization is currently evaluating switching from i18next to another i18n solution, and lingui is currently the most promising candidate.

After converting most of our existing i18next usage to lingui macros using a custom codemod we ended up with many reused translation strings across multiple files. We'd like to avoid string reuse, which can be accomplished by specifying context. It's unfortunately not immediately obvious to a developer when they'd be expected to provide context, as it's to my knowledge only possible to see if a translation is reused by manually checking the po file after running the extract command. This implies that the only safe approach is to manually specify context everywhere, which would essentially nullify the DX improvement which lingui provides by using key-less translations.

Also, specifying context for <Trans> macros is simple enough but I'm not aware of any way to do so for the t macro. Is it possible to specify context for t macros without having to switch to i18n._()?

Proposed Solution

If it was possible to automatically generate default context values for the t/<Trans> macros the above limitations could be avoided. Two possible solution I can think of:

1. Pass a (filePath: string) => string | undefined function in the lingui config that returns the default context for a given file path. If a JS function isn't possible I'd suggest a regex approach like ^.*/src/(?<context>.+?)(\.[jt]sx?)?$ so that leading/trailing noise can be omitted.
2. Allow custom pragmas/directives to control lingui macro conversion on a per-file basis, example:

   /* @lingui context=myContext */
   

   This could apply until the next @lingui comment in the same file.
   This would be more repetitive and easier to forger than (1) since devs would need to remember to add it, although it can be forced via eslint rule or similar.

Alternatives Considered

• Manually specifying context everywhere, which would essentially nullify the DX improvement which lingui provides by using key-less translations.

Additional Context

Looking forward to hearing your thoughts!

[timofei-iatsenko]

That’s quite a unique request! Could you share a bit more about why you don’t want messages to be reused? The main idea behind using the source message as a key is that identical source messages should have identical translations.

Unfortunately, neither of the proposed solutions would work as they’d break some runtime flows. The generated context also needs to remain stable - if it were random, a new ID would be generated on every extract/macro run; if it were based on the filename, translations would be lost when files are moved or renamed.

So, unfortunately, this isn’t something that seems realistic or meaningful to implement.

[mogelbrod]

That’s quite a unique request! Could you share a bit more about why you don’t want messages to be reused? The main idea behind using the source message as a key is that identical source messages should have identical translations.

Sure thing! The primary reason would be to avoid forcing devs to manually providing context to disambiguate source strings that should be translated differently. Unless there's a very quick and straight forward way for devs to immediately see if a string they're marking for translation is going to be reused without waiting for builds etc. we'd like to err on the side of caution to avoid accidental reuse.

Unfortunately, neither of the proposed solutions would work as they’d break some runtime flows. The generated context also needs to remain stable - if it were random, a new ID would be generated on every extract/macro run; if it were based on the filename, translations would be lost when files are moved or renamed.

That's a bummer. With the regexp approach the value ought to have been stable except for file renames as you mentioned. I figured that if the context can be specified through pragmas we'd be able to get stable values even on file moves/renames, wouldn't that be the case?

[Bertg]

Joining in here, and want to make a strong case for re-opening.

why?

Our developers are not native speakers in the 7 languages our application supports. They do not know what strings will need to be separately translated down the line. So it's easy to always provide a context.

Our tooling (Crowdin) already can deal with the issue of duplicate string fairly easily, and I believe other tools do it as well.

How, why re-open?

Unfortunately, neither of the proposed solutions would work as they’d break some runtime flows.

I think option 2 (or similar) will work if you keep it exclusive for the macro options. In my question I suggested adding a file level (or component level) useLinguiDefaults macro. This would yield a no-op at runtime, but would modify how the other macros in the file are processed.

A listing rule could also be added to warns agains mixed usage of macros and non-macros in the same file when the useLinguiDefaults is used, for DX improvement.

in short, I believe a macro-only version should be possible, and this could be reopened.

[Bertg]

@timofei-iatsenko Just pinging you to make sure you have seen these additional arguments ☝️

[Bertg]

Oooh... reopened. Thanks @timofei-iatsenko for reconsidering.
Anything that we can help with?

[timofei-iatsenko]

@Bertg You can create a PR with a feature 😉

A bit of information to consider: lingui don't have any runtime flows which could be broken for now. The id is generated from source string and context during compile time by macro.

But i discovered some time ago that 98% functionality and DX of macro could be done purely with runtime code and without complication you build setup.

This is implementation is in progress and i simply didn't want to introduce something that will later block migration to this runtime only solution.

But your arguments convinced me, and i'm thinking that we can go with a features available only with compilation plugin (macro) and without.

So we need to come up with a solution for compile time plugin which will tackle your's usecases:

1. Generate uniq context based on the file path
   • Pros, would disable string reusage for 100% without any developers effort
   • Cons, would re-generate different id when file renamed/moved and unneccassary drop the translations
2. Add non-runtime directive on the file/module level, such as /* @lingui context=myContext */
   • Pros, allow developers to set it per file, would be stable between file moves/renames
   • Cons, if you goal to not reuse strings, how would you check that this context set uniq for each file?
   • Cons, developer's should not forget to add, if they copied file they should not forget to change it
3. Implement js function in the lingui config:
   • Pros, Most flexible option for JS implementation
   • Cons, will not be possible to implement for SWC version, since it could not execute JS
   • What exactly to pass into this function? module source + path + message ?
   • Could it be done with placeholder string syntax, such as [contenthash][pathhash]? that way it would be possible to implement for SWC as well.

[mogelbrod]

Thanks for sharing @timofei-iatsenko, I mostly agree with your statements 👍
Regarding this:

Cons, if you goal to not reuse strings, how would you check that this context set uniq for each file?

Since it's part of the source code, custom linter rules can be built to enforce it where necessary. I'd also like to clarify that the goal might not be to prevent all string reuse, but to provide disambiguation by default. Having the directive would let consumers decide themselves when contexts should be used, and could example reuse the same context across multiple files if desired.

[Bertg]

Not a fan of 1, I think having explicit code or comments would be the best. As @mogelbrod mentioned is that we want to use this for optional disambiguation; not required.

Obviously something like this would be the coolest:

const Foo = linguiDefaults({context: "Foo"})(...)

const Bar = linguiDefaults({context: "Bar"})(...)

That would even allow "per component" defaults.
On the other hand this would imply that there is a non-macro equivalent of this code... which may be confusing.

I like the comment approach as well. This could possibly also allow "sections" in a file; if not in v1; maybe later.

[timofei-iatsenko]

const Foo = linguiDefaults({context: "Foo"})(...)

I don't like this option because it will not work for vanilla js usages (without react) and would not work for with "lazy" translations with msg macro.

So having a comment or directive eq 'do something' in the scope would the best option for now.

[mogelbrod]

I suggest using comments since directives are somewhat controversial right now.