General Translation Discussion

[zenseii]

Me and @pflugs30 figured it would be better to have this place to discuss matters regarding the translation of fheroes2 in current and future languages. This is all in relation to the current open issue #4516 about adding documentation for translators.

Generally speaking I believe the purpose of all of this should be to alleviate the core team's workload so that instead of doing mundane tasks like translation maintenance and support, they can focus on using their skills on more complex issues.

1. First of all we should probably figure out how and what to document with the core idea being that new translators should be able to pick up and translate the project as quickly as possible, as well as assure consistency between translations.

2. There's talk about having a list of translators and their languages so as to make it easier to know who to contact, both from a dev's perspective and a potential translator's.

3. We should also provide some notes about current state of things and stuff one should know and take into consideration when making the translation, or stuff you should avoid doing.

4. Also a quick summary of how to setup and test your translation is also useful, especially for people who might not have done anything like this before or never worked directly with code.

========================================================================================

So having said all that I can go a bit more in depth with each points I mentioned:

Thoughts on point 1 (press to drop down)

I believe the documentation should strive to be as concise as possible and as clear as possible since we don't know what background the person reading it has. It should probably include a short glossary of the different file types used (po. , mo. etc.) and the programs (poedit, notepad++) used and maybe some of the recurring terminology. Also people will be using different OSes so this will need to be accounted for.

Point 2:
A list of translators is a good idea and whether someone wants to be referenced by their pseudonym or something else, like just a link to their github, works too.

Thoughts on point 3 (press to drop down)

Some notes to this that I can already add are that currently any characters, accents, diacritics etc not found in the English set of characters used in the game will not currently be present in the game. Ex. an `É` might be presented as an `E`. How these are currently adapted is up to the translator essentially. Eventually support for all the characters etc is so far planned, but there are no ETAs.

What all of this means though is that when you're translating you should still write as you would in your language, because the program will take care of adapting these letters. This is to ensure that in the future when these charaters are available you won't need to go back and add them back to the translation - that would be a great waste of time.

Then there's the fact that you need to remember that the strings you are translating will be presented in the game and most likely will have to adhere to a limited area where it is used. Ex. right now for the values of speed you will need to make sure that your translation of ex. "Very Fast" isn't longer than 9 characters, or else the text will start to go outside the statistics windows, particularly for the creature info window where you have an additional number in parathesis: "(x)" following the speed value.

Thoughts on point 4 (press to drop down)

This point will also need to be specific for the OS since I'm not sure POedit exists outside of Windows (_Update: Poedit exists for Linux and Mac*_), or if it is even the best choice on Windows. As for setting up and building the fheroes2 source, this is already covered in the other documentation so a quick reference to that will be fine. It does need to be underlined that currently you will have to build it in order to test your translation in game. This has to do with both being able to apply the language, and with making sure the program recognizes your language's plural forms.

I guess one work-around might be to disguise your translation as another language that you know uses the same grammar for this stuff. Ex. a Danish translation could name its language file as if it were the Norwegian one (nb.po) and see how it looks in one of the releases without having to modify the code and build the project, but this will probably not be an option for most languages. I say this because most people might not be interested in nor have the time to set up a development environment and to learn how to use it.

[zenseii]

I'll keep this as a placeholder for writing a guide or similar that we can link to elsewhere if needed.

Currently you can have a look at this PR #4452 and the three files changed there to have an idea of what you need to do.

In summary this is what needs to be done to add support for a new language from scratch:

1. Make a .po file with your translation. It needs to use a unique filename based on it's ISO abbreviation (Ex. pl.po for Polish.)
2. Edit the Makefile in \files\lang so that your .po file gets converted to .mo when building the project plus add specific character rules for that language.
3. Add your language in translations.cpp so that the game will be able to translate strings that have a singular and plural form.

[pflugs30]

Great writeup, @zenseii! I'm looking forward to working on this one.

[zenseii]

Thanks! It's quite the wall of text but I'm trying to make it as tidy as possible to not waste people's time.

[ihhub]

We should go even deeper in simplification. Not everyone knows what ISO abbreviation is. I think links should be helpful. We need to target people who have no technical skills but they're good on translations. For example, point 1 is not clear: how to make a file? If I'm a Windows user how can I create a custom file extension? If I created a new file and it's empty how do I need to populate it?

Regarding point 3: where is this file located? How can I open it in normal text editor? What should I need to look for?

I think we have to do step by step explanation from the very beginning or create a script which will automatically does the needed setup (I'm in favor for this one).

[ihhub]

On top of this I think we have to write separate documentation for Windows, Linux and MacOS users.

[pflugs30]

Related discussion on the Polish translation: #4486

[zenseii]

So after having assisted BlueRider on Discord with setting up everything, I realized that we should probably make a distinction about what a translator needs to do and what the devs should do. I think the best solution is to have people who want to translate deal the least amount possible with setting up stuff and compiling stuff. They should just worry about translating in the .po file.

I'm trying to think of a way to facilitate this. Maybe someone who has everything setup could help them make the necessary changes to translation.cpp and the makefile in a separate branch that the translators can grab a build from. This way they would only really need to:

1. Edit their .po file
2. Compile it to .mo
3. Move it to their fheroes2 installation's files\lang folder for testing.

The reason they have to compile the .mo themselves currently is because the characters that don't exist in English need to be replaced, and this is specified in the makefile. Compiling with either POEdit's native function or somewhere else won't do this obviously. They could always go on the fheroes2 Discord channel and ask someone there if they can compile it and send it back, or just post on github and ask for it to be compiled. This solution is quite slow since usually you'd want to check things quickly and move on, while this latter solution could lead to lots of delays waiting for someone to be available to compile it.

This will all no longer be necessary once more characters are supported of course.

[zenseii]

After having thought a while about ihhub's advice on Discord about telling translators to make use of the repo's CI\CD pipeline, I realize that the "only" setting up step strictly necessary for translators is to get a way to compile their POs to MOs. For Windows users this could be to setup Cygwin, which is still quite a hassle, not just the setting up, but also the usage of it, especially for someone not familiar with these things. If anyone knows an even more straightforward way to run MAKE and the other commands necessary to compile the MO in a Windows environment, then please share.

In the spirit of keeping the required installations and the usage of space on a translator's PC to a minimum, using the repo's pipelines will at least spare translators from having to install an IDE, which is very overkill when you're just using it one time to make small changes to two files.

However, they would still need a way to make their changes to the code and personally I think using a lightweight source code editor like Notepad++ is more than enough.

[pflugs30]

I'd like to make a few comments here that we discussed in the Translations Discord channel. We ran into a problem today with @zenseii's work on translating the shortened Artifact names (see #4436 for reference). One of the Artifacts has a full name in English less than 18 characters and thus it doesn't need a shortened version. Unfortunately, the full name translation in Norwegian exceeds 18 characters, and thus it would need a Short Name. Since the English string is used as a key for the translation string lookup, there isn't a way to shorten it yet. As such, we had to shorten the Full Name to less than 18 characters. I'm sure we're missing other Artifacts in other languages.

One possible solution to this challenge would be to do the following:

1. Treat Artifacts as a class rather than simply an enumeration. Include a FullName and a ShortName property.
2. Change our translation strategy to not use the English translation as the msgid but instead an enumeration or key.
   • In fact, we're already doing something similar to that with certain strings, such as luck|Cursed and morale|Treason.

Since there are other bonus types as well, such as Heroes, Spells, and Resources, we may also face some instances with these types beyond just Artifacts.

I know we're trying to push towards a v1.0 release and not do any major refactoring of the codebase or translation strategy. I'm documenting this issue here so that we can address it at the proper time. I believe the work will be well worth the effort and enable us to be more nimble and responsive to other translation issues in the future.

[ihhub]

If we have to do refactoring for translations then we should do it. Having just okay-ish solution is good but we want to have the best one!

[ihhub]

Hi @zenseii and @pflugs30 , this is a good stuff and I'm fully supporting this. I'll prepare my notes about this and then we can start making a documentation file for any translator.

[zenseii]

@pflugs30 and @ihhub I've made a quick draft of the documentation page just to sort the current points we have made and to make myself acquainted with how making wiki pages here works:
https://github.com/zenseii/fheroes2/wiki/Translation-Guide

It is very far from anything final, and I imagine like Ihhub said that we might have to make separate subpages for the various parts. I'm also waiting for ihhub to post his notes so that I can make adjustments according to them.

[zenseii]

Also I made the guide on my fork since I'm not sure how to make a PR of a wiki page yet. I believe I have to make something like a "Translations.md" and push it to the docs folder? In addition, the page above is useful for knowing what th wiki will actually look like while working on it.

[zenseii]

I also have some questions:

1. Should translators need a program for making PRs like Github Desktop, or is there an easier way they can make a PR?
2. Is compiling the MO with makefile still necessary?

[zenseii]

I can answer nr.2 now myself after testing and having others test. Compiling with the makefile is still necessary. If you use poedit's integrated and automatic .mo compilation the letters that are not supported show as . in the game. There is already work being done to add the missing letters so this will eventually not be a problem, and will make compiling up against the makefile unneccessary.

[zenseii]

I just checked what packages are needed for cygwin on Windows to compile the .mo and they are:
gettext-dlevel
libiconv
make

These are also all that are needed to make the .pot file.

[heroesiiifan]

The German translation is unfortunately still quite empty at the moment.

Is there a way to somehow import most of the text from the German version? And to use this as a basis?

[zenseii]

Could you please write in English if you can? Someone is currently working on translating in German, because to my understanding the current German translation is close to zero.

I'm sure help would be appreciated.

[heroesiiifan]

Sorry, I used Deepl and was too stupid to copy the right text. :)

[zenseii]

There is no way to import it. Translation is done by manually translating text in a .po file, in this case de.po file found in files/lang folder of the fheroes2 source. You should open it with a program called poedit and use that to edit it.

[yvesgurcan]

Hello folks, I've submitted #4895. This is meant to be a starting point to documenting some of the technical processes around updating translations and isn't exhaustive at all. Hopefully, this should address some of the points brought up in this discussion and can be iterated on to provide more support to translators.

[Mr-Bajs]

I guess some you want the .po files as clean as possible, that there should be no # comments in the files.
Thought it would be great if every string would have an comment that limit the amount of letters in each string should have at the most.
Heroes are designed for the english language and the space for a word is based around this. I assume several languages have longer words with more letters, than the english default one. It can look pretty bad translating into a to long word. It's hard to know without checking the translation ingame.
Translation would be easier if the translator had any info in the file for how many max letters a recomended. Sort of something like above the string.

Max amount of recomended letters: 4

Just a thought.

[zenseii]

Yes, I've thought about doing this but not had the time to. There's also the point that many UI things are quickly being reworked which means we'd have to go and change all of these comments. If we decide on doing this then we would first have to look at how we imagine things will be and what makes sense to do. E.G. in game buttons are still WIP and their implementation can quickly change to allow longer words if needed.

There's also the point that the size of the letters depend on the letters themselves and even the alphabeth in use (see Cyrillic as an example).

Usually when I have more time I try to comment this for translators because I'm familiar with all the strings and what their limitations are.

Another point is that it is also important for us that the translators actually run the game and are somewhat familiar with it when translating, rather than some generic translation that doesn't really fit. This doesn't always happen though, it is our goal.

[Mr-Bajs]

I found a minor inconsistency.
In the game some times it refers to number by numerical (0-9) an sometime by words (one, two etc).

Example Barbarian buildin The Coliseums description:
The Coliseum provides inspiring spectacles to defending troops, raising their morale by two during combat.

Same as Sorceress buildin Rainbow
The Rainbow increases the luck of the defending units by two.

But or for example the artifact Fizbin of Misfortune
The Fizbin of Misfortune greatly decreases your morale by 2.

This is rather inconsistent and in my mind changed to the numerical use (1,2,3 etc).

Also another thing several artifacts, doesn't tell in the descptions the value of their effects are. They just tell you what they incease the heroes morale but not by how much, so you have to right click in the stats to know. That information should be accessible just by right clicking in the artifact.

I suggest that the actual values of the artifacts should be added in their descriptions.