add inline annotations in language files

[felixhaeberle]

Problem

Currently, when translating a language file, it is difficult to know the meaning of the text in the reference language without having to look it up in another file or context. This can be time-consuming and frustrating for developers who are trying to quickly and accurately translate language files.

Solution

To address this issue, I propose adding inline annotations to language files that will display the text of the reference language alongside the translated text. This will provide developers with immediate context for the text they are translating, without having to reference another file or context.

[ivanhofer]

I would show this inline annotation in a line above and not after the text. It will make it hard to read if it is a longer text.

How do you know if the file you have opened is a Resource file?
The plugin will probably need to tell you that information.

I'm currently investigating #646 and @samuelstroschein suggested to create a proxy to retrieve that information: #646 (comment)

[felixhaeberle]

@ivanhofer how to find out if the file is a resource -> from the inlang config plugin json pathPattern, or, as you said, from another plugin pathPattern (yaml)

[samuelstroschein]

@felixhaeberle an application doesn't know what a plugin sets. You can't retrieve the pathPattern (which btw doesn't exist for many plugins) from the application. @jannesblobel had the same logic mistake yesterday :D

You could track fs.readFile calls with proxies as Ivan suggested. Given that this feature request popped up three times now, maybe something to add to @inlang-git/fs which needs this information too to establish lazy loading. @araknast maybe worth it to expose relavant/retrieved files so that apps can use this information?

[felixhaeberle]

@samuelstroschein I do not have that logical mistake, but in reality, we need this information provided somewhere. at best in a plugin (for now). we can detect multiple points to retrieve that information. if no information is provided, this feature (and others) will not work 😄

[samuelstroschein]

@felixhaeberle

how to find out if the file is a resource -> from the inlang config plugin json pathPattern, or, as you said, from another plugin pathPattern (yaml)

This is a logical mistake. You want to access scoped data from plugins which is not possible. Furthermore, the pathPattern isn't even used by all plugins. Jannes made the same logical mistake yesterday by thinking scoped plugin data can be accessed.

The only way you can retrieve relevant files is by proxying $fs and track what files have been touched because $fs is passed from the host (app like the editor, ide extension) down to plugins.

[felixhaeberle]

@samuelstroschein I do not disagree but want to say one thing: A lot of functionalities in the inlang architecture are exactly bound to specific plugin behavior. Otherwise it will not work. For example the editor, and also the IDE extension, if this data isn't provided by a plugin, no background magic will resolve this (atm, future plans not included). Of course it's really modular, but at the end, we are currently architecting with a inlang.config.js approach and functions which a derived from the plugins within.

So you are right: an application has no idea about the data from a plugin will be there, but it also doesn't work if it's not there. Or does any of the inlang product work without a config file? And especially: does it retrieve value without plugins?

If we want to ship this feature now, we can set this information by a plugin. If not, it's a alive end (opposite of dead end) of a feature, not existing, but also not breaking the rest of the behavior.

[ivanhofer]

A plugin could expose a isPathResource(path: string) function, but this will increase the development effort of plugin authors. A easy way to achieve the same behavior is it to use a proxy. No plugin needs to change and if we later decide that all plugins need a isPathResource function, we can remove the proxy.

[samuelstroschein]

@felixhaeberle I don't understand your points. Seems like my explanation is unclear.

The knowledge of what files are used by inlang is a common request as laid out in #726 (comment). This request can be fulfilled by not touching plugins but modifying/proxying the inlang environment. The ability to "control" plugins is exactly why host applications expose the inlang environment to plugins.

Adjusting plugins to expose what files are used moves the burden of tracking what files are used from the host application to plugins and relying on the correct implementation of external developers. This would be a bad design choice.

Besides, the information on what files are used is a common need for apps. Thus, the inlang environment should automatically expose this information. Automatic exposure can be achieved by extending @inlang-git/fs to expose this information moving the implementation details out of plugins and host apps.

[felixhaeberle]

@samuelstroschein We're on the same page! 😄 It's only a question about when we want to implement it and how. You say it would be best in @inlang-git/fs and I totally agree! But I also see other possibilities like I (an @ivanhofer) outlined.

[araknast]

You could track fs.readFile calls with proxies as Ivan suggested. Given that this feature request popped up three times now, maybe something to add to @inlang-git/fs which needs this information too to establish lazy loading. @araknast maybe worth it to expose relevant/retrieved files so that apps can use this information?

I'm not sure how you would distinguish calls to readFile that come from the editor from ones that come from other sources (e.g. isomorphic-git will end up touching pretty much every file multiple times, not to mention git objects).

Perhaps we could have a set of general use bits in the stat information, then the value of the bits can be set by specifying an option to readFile?

[samuelstroschein]

I'm not sure how you would distinguish calls to readFile that come from the editor from ones that come from other sources (e.g. isomorphic-git will end up touching pretty much every file multiple times, not to mention git objects).

Will isomorphic-git touch every file?

If we implement lazy loading of files/lazy cloning, isomorphic-git should only clone/touch files that are "used' by the host application. Otherwise, isomorphic git would clone entire repos.

[araknast]

If we implement lazy loading of files/lazy cloning, isomorphic-git should only clone/touch files that are "used' by the host application. Otherwise, isomorphic git would clone entire repos.

For lazy loading we would still need to create a "fake" version of every file in the root directory so that the user knows which files exist, at least that's how I envisioned it working, although I'm not entirely clear on how the git-sdk is going to be used in vscode.

[samuelstroschein]

For lazy loading we would still need to create a "fake" version of every file in the root directory so that the user knows which files exist.

Yeah true but what exists and what does not is unrelated to "reading the contents of a file". Tbh I am excited about the solution we will come up with. Its an interesting engineering challenge

[araknast]

Yeah true but what exists and what does not is unrelated to "reading the contents of a file".

Hmm true I guess that would (hopefully) only involve calls to writeFile. If we can guarantee that readFile will only be called on resource files then I guess there is no issue. Would lazy cloning only be for plugin/editor files then?

[samuelstroschein]

Would lazy cloning only be for plugin/editor files then?

For entire repos. If we control the environment, as in the editor, we can ensure that every "component" uses our provided fs for dynamically lazy loading/cloning file contents.

[araknast]

For entire repos. If we control the environment, as in the editor, we can ensure that every "component" uses our provided fs for dynamically lazy loading/cloning file contents.

In that case then, wouldn't readFile end up getting called on non-resource files? E.g if a user wants to edit their package.json for example, they would need to call readFile on it in order for it to be loaded. Or are we using a different mechanism for lazy loading?

[samuelstroschein]

In that case then, wouldn't readFile end up getting called on non-resource files? E.g if a user wants to edit their package.json for example, they would need to call readFile on it in order for it to be loaded. Or are we using a different mechanism for lazy loading?

An app would call fs.readFile when a user opens a file like package.json. The moment a user (a program) opens a file -> clone the file. Not before, and certainly not after :D

[araknast]

An app would call fs.readFile when a user opens a file like package.json. The moment a user (a program) opens a file -> clone the file. Not before, and certainly not after :D

Right, that makes sense. Then I guess my original question applies of how do we distinguish a call to readFile that comes from the user opening e.g. package.json, from one that comes from the editor reading a resource file?

[samuelstroschein]

Then I guess my original question applies of how do we distinguish a call to readFile that comes from the user opening e.g. package.json, from one that comes from the editor reading a resource file?

Indeed. That's the question.

I just realized that the approach of passing a proxied fs to plugins might not be a workaround but the only solution, even if inlang-git/fs tracks internal filesystem calls.

[openscript]

I would show this inline annotation in a line above and not after the text. It will make it hard to read if it is a longer text.

@ivanhofer:
I'm not sure if this is possible. There is a feature to display source actions above a line (Gitlens) uses this heavily, but maybe if many extensions use this, it becomes messy. Though I agree with you, that it would be better to have it above for readability. I think this should be discussed in another thread than here.

---

@felixhaeberle:
Looking up the default language and display it the same way as inline translations in code, shouldn't be hard.

Estimate: 2h

[samuelstroschein]

@openscript from your experience, is this a must-have feature?

If not, I propose to transfer this to "Feature Requests" in discussions and let users vote.

[openscript]

@openscript from your experience, is this a must-have feature?

If not, I propose to transfer this to "Feature Requests" in discussions and let users vote.

We don't use or need this feature, because other tools offer a context tool tip, which is convenient enough.

[felixhaeberle]

@openscript This is what I thought too, this is not really nessesary if you have a context tooltip! 👍

[felixhaeberle]

@samuelstroschein Are we still considering this with the new storage layer?

[samuelstroschein]

nope introducing a non-readable storage format