First run users should get a popup that explains what the program does

[XapaJIaMnu]

What the title says. Especially about downloading models.

[jelmervdl]

Quick mock-up. Something like this?

Could be made a bit interactive, e.g. update the screenshot with arrows when you hover over each of the steps.

I'm a bit worried people will try to interact with the screenshot. Maybe it's technically possible to temporarily draw the main window inside that dialog while the dialog is open (and make it stand-alone as soon as you click "Close") but that also feels gimmicky. Maybe it works better without a screenshot.

[XapaJIaMnu]

Hmm... I have a couple of problems with the screenshot, but I am not sure I can propose a meaningful solution. 1) The screenshot may work very differently from your platform's appearance. 2) Inevitably as you said, someone will try to interact with it, and be disappointed.

I was just thinking of a simple Dialog option such with things such as. "Go to the drop down menu to select/download translation models, go to the settings to increase/decrease the font size and to configure advanced translator settings."

This is not a very good tutorial, but may do what is necessary. I find the interface self explanatory, but a few people asked for pointers ;/

The ideal solution would be a guided, interactive wizard that expected the user to click in a few places. eg "Click the download models drop down menu" and the drop down menu is highlighted at the same time.

[kpu]

Translate locally runs on your computer using models for each language. Would you like to check the Internet for the latest models and download them when you select a new language? (UI hinted option) No sends them to our website and an option to configure the directory where they've already downloaded models.

[jelmervdl]

The other option I had in mind was something like https://introjs.com. I personally hate these, but they do guide the user quite well. And since it uses the actual application, no issues with screenshots.

There might be a qt library made by someone to implement such a tour. I don't think it's too difficult to implement ourselves, but it will be a bit more involved than just popup dialog.

[XapaJIaMnu]

Yeah I like that bit, but unsure of how difficult it is, and what tools we have for implementing it.

[jelmervdl]

@kpu do you mean we should ask the user on first time start up what the "Download models…" option should do? (I.e. show the list or open a website.) And second, should we after that choice immediately do that?

Very bad mock-up (problem is I wanted to make the preferred option the biggest one instead of just "yes")

[XapaJIaMnu]

As far as model distribution is concerned, we could (later on) make an installer for windows and mac that ships with compressed models and the user chooses which ones they want at that steps. I had a few win users complain to me that there is no installer.

[kpu]

We can probably shorten that text.

Paging @ChrisBurnsOneOne

[ChrisBurnsOneOne]

Some thoughts :

-I don't think "models" is very meaningful for the average user who'll end up using this. I would refer to them as something else, even if it's simplistic like "dictionaries" or "libraries". It won't convey the complexity of what's going on, but users are unlikely to care about that so long as it does what it's supposed to do.

-"translateLocally needs to download a library for each language it translates. translateLocally can download these libraries automatically, or you can do this yourself. Do you want to :

                                                      <dialogue boxes>

There's an adjunct issue if the libraries are ever updated, as this will need to be explained to the user since the crux of the app is that it doesn't communicate externally to accomplish the translations.

[kpu]

The onboarding experience sucks pretty badly right now, with an error alert saying that you need to download models first.

[jelmervdl]

Better suggestion:

On macOS the buttons and icon look very old-fashioned as the whole concept of a link-button isn't really something that's part of the Apple design language at the moment? On Windows and Linux I expect them to be a bit more native

[XapaJIaMnu]

I like it!

[kpu]

Maybe we should have a page to download the models from :-)

[jelmervdl]

I was assuming we'll have that at some point (before this makes it into the release), as well as an easy way of importing those downloaded models.

Edit: also this popup should only show if you don't have any translateLocally models installed. If you would download a version that comes with models, this popup makes less sense and you can just get started immediately,

[XapaJIaMnu]

The current behaviour scans the directories where the translateLocally executable is so importing is as simple as copy/pasting models. They do need to contain a certain config file which we are not explaining in any way other than throigh the source code.

[kpu]

For windows at least it's better to manufacture our own file extension so the application can be launched for that extension. Like jar is really a zip file but launches java. I apologize for raising java as an example.

[XapaJIaMnu]

Technically all three OS-s have mime type handling, it's not too difficult to implement that.

[kpu]

We should really make progress on this one in the release. There are business decision makers trying it once or twice. I don't think we should wait for proper download-it-yourself infrastructure.

[XapaJIaMnu]

If we distributed a zip file containing the exe + a number of models in the same directory, the app will detect them and avoid the ugly message.

[jelmervdl]

Shipping models would also put more emphasis on "no cloud necessary!" not even for getting started.

Model sizes: https://gist.github.com/jelmervdl/1a48816e4c3643ff5d9e1fd6821bc499

Shipping all tiny models would add another 150mb to the package, which might be a bit much, compared to the current release sizes:

10.27MB https://translatelocally.com/release/translateLocally-v0.0.2+be52de5-Ubuntu-20.04.avx.deb
82.39MB https://translatelocally.com/release/translateLocally.avx.exe
38.56MB https://translatelocally.com/release/translateLocally.avx.dmg

Additionally, we'll need to figure out how to ship these additional files. I.e. on Windows, do we now need an installer? Or do we just distribute a zip and hope that people will figure it out? On Mac, do we ship the models inside the application bundle? And if so, would it pick them up correctly? Linux… where does the package write the models to and will the binary be able to detect them there.

I remember recalling we already had a plan to ship a batteries-included version, so figuring all of that out might need doing anyway to make that version. And while this issue of the intro popup isn't released yet, we could opt for only distributing that batteries-included edition.

[jelmervdl]

Oh! I see what @XapaJIaMnu is getting at.

For demo purposes, being able to point to a Windows zip file with the de-en & en-de models included would make sense and would be an easy "fix" I suppose.

[XapaJIaMnu]

Yeah, the model searching code first checks all the current subdirectories for marian configuraiton files and then also checks the system configuration directory. No need to even manually import.

[ChrisBurnsOneOne]

Unless this is for a completely managed demonstration, you need an installer. There are some related issues; a recognisable icon and even a loading screen for 3-5 seconds (which doesn't get in the way of actually doing translation) will help reinforce what it is and does.

[XapaJIaMnu]

Are we happy with the current popup for first run? I demo'ed to two users and they figured it out quite fast.

[ChrisBurnsOneOne]

I'd need a compiled Windows version to take a look. Can be emailed at my Edinburgh address if that helps.

[kpu]

https://github.com/XapaJIaMnu/translateLocally/releases then click on "Assets"

[ChrisBurnsOneOne]

I see the message now; it looks suitable.

Ran into an adjunct issue, however - on a Windows PC that's run earlier versions (installed doesn't seem to be the right word, as there's nothing to uninstall in the control panel), I don't actually get the message popup - TranslateLocally just opens. I had to switch to a different PC (Windows 11) which has never run TranslateLocally to see the popup.

[XapaJIaMnu]

@ChrisBurnsOneOne, translateLocally checks if the configuration directory is present, which gets built after first run for a given user. You are right though, we don't currently have an uninstaller.