About Translations.

If someone who speaks two languages is bilingual and someone who speaks three languages is trilingual, what do you call someone who speaks only one language? An American!

Updated 10 April 2022: PR 2870 merged. I’m updating this post to reflect that.

In Why Do Developers… Develop? I praised the work of people who contribute language translations to free and open source projects. It’s important work that never gets enough credit.

It’s not easy work per se, because writing clear and accurate technical documentation is never easy, but if you have a good technical understanding of what users want to accomplish, a few technical skills (editing files, using Git branches, and submitting pull requests), and conversational skills in a language besides English, you can help make your favorite open source project reach more people.

The maintainers will really appreciate it too.

How Translation Works (The Helpful But Not Entirely Accurate Version)

Here’s what you need to know.

When you launch the Dogecoin Core Qt GUI, you’ll see a friendly Doge face pop up and a lot of text. Every menu has text. Every notification has text. Every widget has text.

It’s all text.

If you look in the GUI source code, especially the .cpp files, you’ll see text, and you should see it look like tr("Here is some text"), with that tr() function prominent.

For example, when I added the “Import Private Key” menu entry in PR 1856, the actual text is wrapped in that tr() function. Qt provides that function (tr is short for translate) for GUI code.

When you compile the GUI, the Qt system reads the text provided to every tr() call and replaces it with a placeholder. When you run the GUI, the Qt system looks at the locale information you’ve provided and chooses the appropriate translated text.

What does “appropriate” mean?

Look at the French Canadian translation file, something called src/qt/locale/bitcoin_fr_CA.ts. This is an XML document that associates the English text in specific locations in the source code and GUI with a translated version.

Now that I look at it, I would have expected phrase secrète or at least mots de passe, but I don’t speak conversational French Canadian, so what do I know?

Anyhow, when Qt and everything gets compiled into the dogecoin-qt program, Qt knows how to swap the text that’s in the source code as English for the text in the appropriate translation file for what you want to read. If you want French Canadian text, you’ll have to enter your mot de passe instead of your passphrase.

Of course, this only works if someone has done the hard work of…

Translating Things That Need Translation

Now you could go through every merged PR and look for new or modified text and manually update the translation files you want.

… or you could look for untranslated text because it looks something like:

        <source>Please enter an address.</source>
        <translation type="unfinished"></translation>

In that case, put the translated text on the second line between > and < and remove the type="unfinished" so it reads:

        <source>Please enter an address.</source>
        <translation> your translation here </translation>

Easy, right?

Not quite.

How Do These Files Get Made?

My PR 2870 made it easier to regenerate these files that need translation.

With that PR, you can run the command make translate language=... in the src/ directory of the Dogecoin Core source code and regenerate the translation file for the language you care about. Then open it up and translate away!

For example, if you speak Spanish in the Mexican dialect, you want to run make translate language=es_MX to update the transations for the Spanish (es) language’s Mexico (MX) locale. You’ll see changes to the file src/qt/locale/bitcoin_es_MX.ts. Modify that file, create a PR, and other Spanish speakers in Mexico will see your changes.

That PR also updated the Dogecoin translation policy doc to explain this commandin more detail. That entire file gives a good overview of the project’s transation guidelines.

There are many little details that are important, but my personal opinion is that getting some things translated now is better than waiting a long time to get all things translated. The better the coverage and the translations, the friendlier this or any other free and open source software is to new and existing users.

That’s the point, isn’t it, to make things easier for other people?

Happy hacking!