I'm contributing with a Spanish (es_419) translation for this project

[tmarplatt]

Hello. I'm opening this ticket merely to inform that I am starting a full translation of novelWriter to the Spanish language (Latin American flavour). novelWriter is such an amazing piece of literary software, and I want to help its adoption among the LatAm community.

Since I do not know how much time it will take before submitting a PR, I'm opening this issue in case other contributors search the Issue tracker for the language name. You can find my novelWriter fork here.

Any comments, advice, it's all welcome.

[vkbo]

Great! Thanks a lot. There is a README in the i18n folder that explains how to add new translations if you haven't seen it already. The initial translation is a bit heavy since there are a lot of labels for all the settings. The Qt Linguist tool makes it fairly easy to do though.

I will make sure the es_419 tag is understood by the GUI. I make a few assumptions when I parse the language tags, so I'll just double check.

[tmarplatt]

Yes Linguist is a pretty solid tool for localisation, and I've worked with similar tools in the past. I'm already making a lot of progress. :)

How should we go about mistakes in the original strings? I've already spotted a typo.

Also what about style / usability suggestions? There are some descriptions whose English wording could be improved and, in some cases, entirely reworded.

[vkbo]

How should we go about mistakes in the original strings? I've already spotted a typo.

If you spot any, please just make a note and list them in this issue? I'll do a manual correction of all the files afterwards. I prefer not to regenerate all the files as it clutters the change history, so I usually do a search/replace for the corrections in both the source and the .ts xml. This also helps to preserve the previous translations.

Also what about style / usability suggestions? There are some descriptions whose English wording could be improved and, in some cases, entirely reworded.

If there aren't too many, perhaps just list them as suggestions as well?
Keep in mind some sentences are a bit awkward in order to keep them short where there is limited room on the GUI.

Also, of you can, try to keep the translated strings short where they are meant to fit on tab labels and such. Sometimes it's better to find a close word rather than a direct translation. I did that with some of the Norwegian labels.

[vkbo]

Also, I just looked at your fork. Please don't commit directly to the main branch. That causes all sorts of issues when merging the changes. Make a local branch instead. See the Contributing Guide.

[tmarplatt]

Very well.

I noticed that QGroupBox title length actually pushes the boundaries of its parent box outwards, so e.g. a title long enough (like the topmost title here) introduces a horizontal scrollbar. Yet such extended length by itself should not be enough to overflow the parent panel's width. Maybe it's a QT thing, maybe some additional padding is being calculated. I don't know if you can fix that.

[tmarplatt]

@vkbo I would like to continue translating against your most recent merge #904 while I'm still in early stages. Should I merge from my local branch?

[vkbo]

Yes, labels do not wrap by default, so if there is any way you can change that label to something shorter that still makes sense for formatting titles, please do so. This is one of the cases where I think the translation from English doesn't have to match exactly and instead should be a meaningful grouping label with a similar meaning.

On some locations I have hard coded an upper size limit where text will eventually be cut if the translations are too long. Otherwise it will mess up the GUI. I think it's mostly on tab labels, but keep an eye out for those too. I added them when the Portuguese translation was added. The latin-based languages can be a bit verbose at times compared to English and Norwegian.

As for the changes of PR #904, I don't think it should affect the translations. It's mostly a cleanup PR that changes which string formatting method is used as the default (since I no longer support Python 3.5) and improves test coverage.

[tmarplatt]

The lupdate tool (as invoked by python3 setup.py qtlupdate) strips all <translatorcomment> tags from the .ts file markup, which is a shame because during translation I'm leaving comments for future reviewers/translators, e.g. for clarifying string context.

I don't know if that's something you can address in your setup.py script. It will be especially useful if e.g. some translator from Spain decides to port the es_419 translation into plain es, which should be much faster than to start from scratch.

For now I'm manually recovering the comments with the diff tool, so nothing is lost.

[vkbo]

There doesn't seem to be an option that does that for the pylupdate5 tool. It is very basic.
Even if you manually preserve the comments, others may not do that in the future if the command is run and the files committed.

[tmarplatt]

In looking for a solution, I have tried replacing pylupdate5 with lupdate.

lupdate doesn't strip <translatorcomment> tags, which is good, but it's also much stricter in parsing source files. For every tr() call it considers invalid a string is ommited from the generated .ts file, and a good number of strings are lost as a consequence.

[vkbo]

This was added by @bkmeneguello, so I never looked into the difference in detail, but I don't think the lupdate tool can be used directly. It doesn't parse all valid Python string formattings as far as I know.

[tmarplatt]

Another issue I found with pylupdate5 is that it doesn't bypass HTML entities when parsing <translation> nodes, and proceeds to convert & into & so e.g. <b> becomes <b>.

In relation to the missing <translatorcomment> nodes, what if setup.py caches every one of them from the .ts file before handing it to qtlupdate, and write them back when it's done?

[vkbo]

I'm not sure I understand what you are referring to with HTML entities. How exactly do they get double-encoded in the TS file?

Also, I think perhaps the pylupdate5 tool is a bit outdated. The documentation states it is equivalent to lupdate (see here), but as far as I can tell it produces a TS file of a different version. The pylupdate5 produces a TS file of version 2.0, while the Qt Linguist will save it as version 2.1. Perhaps this is where the change comes in.

[vkbo]

I've been reading the Qt documentation for a bit, and I'm wondering if the lupdate tool in pyside2 or pyside6 may do a better job. It's definitely worth looking into. I'll see if I have some time this weekend.

[tmarplatt]

That would be excellent, thanks.

I'm not sure I understand what you are referring to with HTML entities. How exactly do they get double-encoded in the TS file?

Sorry I should have said XML entities (my inner webdev is showing). When Linguist stores the .ts file it replaces &'"<> characters with their predefined XML entities, all according to spec. But then, pylupdate5 seems to not parse these entities and proceeds to escape ampersands once more. At least mine does (I tested versions 5.14.1 and 5.15.5).

[vkbo]

I understood what you meant by HTML entities, I'm just not seeing the double encoding you describe and was wondering under which conditions you encounter them. I cannot reproduce this with 5.15.2.

I also see there is an issue with the novelWriter.pro file which has an outdated entry causing a dialog to not be translated. It is really annoying that the pylupdate5 tool requires this outdated .pro file. I'm going to look into ways of improving this too.

[vkbo]

Just a heads up. I just merged some fixes that affects the translation files, so you should update your main branch and regenerate your Spanish file. A dialog box was missing in the translation set (the "Project Details" dialog).

[vkbo]

Further update: I tested the pyside version of the lupdate tool for Python source, and it is even more outdated than the PyQt5 one, so that will not work.

I assume the tool released by Qt Company for Qt6 is up to date, but this project will not support Qt6 for quite some time yet.

[vkbo]

I just merged #915 which rewrites the way translation files are generated and built in setup.py. The old commands should work as before, but they no longer read the novelWriter.pro file. The list of source files and translation files are generated on the fly. This should avoid the issue of files dropping out of the translation framework, which has happened a few times now.

The new version of qtlupdate can take TS files as arguments, which makes it easier to update specific files or add new ones. I've updated the i18n/README.md file accordingly.

Merging this into your branch shouldn't make much of a difference, but it will create a conflict with your copy of the novelWriter.pro file. You can now just delete that file.

[tmarplatt]

Brilliant. Thanks for taking the time of improving the toolset, which sometimes can feel an ungrateful task. This will further streamline the translation process and perhaps make it more enticing for new translators to collaborate.

I'll get to merging, testing and finishing the translation.

[tmarplatt]

The i18n readme currently repeats itself a lot and is somewhat disorganised, so here is my attempt at a rewrite (on a new branch). I left all the important bits while improving its readability and structure.

Please let me know what you think.

[vkbo]

Sure. It's been rewritten a few times, and probably needs a cleanup. Just skimmed it quickly. It looks fine. Just make a PR and I'll have a proper read-through tomorrow.

Thanks!

[tmarplatt]

So it's been a while since I've written any Python code, but I made this setup.py hack that allows running qtlupdate as usual with the ability to retain translator comments: it stores them in a xml.etree.ElementTree.ElementTree and then to disk. And it only re-inserts comments belonging to strings that remain unchanged after running pylupdate5.

I tested it with the practically finished es_419 file and no errors, all comments remain, XML structure and format is retained. What do you think? @vkbo

Finally, I have a list of string change suggestions coming up, perhaps those should go into a separate issue thread?

[vkbo]

It's decent Python code. Just a few redundancies related to scope of objects. I'm guessing you're more used to C/C++? Anyway, nothing that can't be easily fixed.

That said, I'm still uncertain about adding such a hack. Especially since it makes a few assumptions about the file content and structure without checking file version. I would probably rewrite it a little before taking it, but it may be an unnecessary duplication of effort. The issue is fixed in the PyQt6's pylupdate, but unfortunately not backported to PyQt5. The entire tool seems to have been rewritten. It may be simpler to just include the code from PyQt6 and put it in the setup directory. That way, we control how these files are generated and by what version. The pylupdate tool and novelWriter use the same license, so including it isn't an issue either.

Just make your PR with the TS files including comments, and I'll use that as a basis for testing that I can preserve them with the PyQt6 code. If we can't, then we'll merge your changes to the setup.py file and just use that hack instead.

[vkbo]

Ok, I've added the PyQt6 version of pylupdate in PR #920, but there are some minor issues. The main one being that the tool uses a different indentation of the TS XML than the Qt Linguist tool does. This will generate rather large diffs if files are added without first being cleaned up with Linguist. It may not be a big issue though. I may add a simple fix that reindents the XML after it's been generated.

I also noticed that the TS file format 2.1 will allow multiple location references in the XML. This means you assumption that translatorcomment should be inserted at index point 2 does not hold.

Edit: Update on the file cleanup. There are more issues with the XML formatting than just indentation. So I may as well leave it as-is and only allow TS files that have first been through Qt Linguist.

[vkbo]

Thanks a lot for taking the time to make this translation. I know it's a lot of work.