Good translation requires rewriting the sourceGit<br>ByBit

English

Learn Git in code editor

English

Good translation requires rewriting the source

Blog/ 2026-08-04 / Alexander Shvets

Over the past two months, I released the first batch of localizations for GitByBit, letting roughly 10% of the planet learn Git in the best possible way, all in their native languages:

Spanish

Portuguese (Brazilian)

Ukrainian

Russian

Why these four languages?

Style and tone

When writing GitByBit and later translating it, I aimed for two things:

a friendly, informal tone;

the day-to-day tech lingo developers actually use among themselves.

I couldn't rely on the official Git docs as my main reference because, as it turns out, they often sound too formal and translate terms that real developers prefer to keep in English or transliterate.

Some passages even read like lightly edited early machine translation. That may partly be a consequence of how fragmented the documentation ecosystem is: different resources and languages have been maintained by different community projects over many years, without a single editorial voice spanning all of them. The result is hit-or-miss quality and terminology that doesn’t always match how developers actually talk.

In the real world, non-English-speaking devs use a mix of English, translated terms, and local slang. The proportions vary between languages—and even between countries that share a language. Spanish developers in Spain, Mexico, and Argentina, for example, may use different slang and idioms. In Spanish, one team may talk about el área de staging, while another calls it el área de preparación ("preparation area"). One keeps tag in English; another translates it as etiqueta ("label").

That lack of a single correct answer drove me crazy until I accepted that no translation would ever be perfect. At the end of the day, you’re mostly translating for people whose English gets in the way of learning. Those who are entirely comfortable in English may choose the original from the start. Aim to make the translation clearer, livelier, and more human than the official docs. That’s a pragmatic and achievable goal.

Forget perfection! But do thorough research, make educated guesses when usage is ambiguous, and keep your choices consistent. Then ship the translation, hope for the best, and improve it in response to user feedback.

Your PT-BR version of the GitByBit is perfect. I couldn't write it any better, you can continue displaying it to everyone

— Ivã S.

Language as a result of collective choices

It's fascinating how language evolves in seemingly random directions thanks to collective human choices. Let's take Spanish and Portuguese. Both are very similar in terms of linguistic constructions and vocabulary. Both have been exposed to Git for 20 years. Yet over time, their developer communities settled on different conventions for Git terminology.

In Spanish, branch becomes rama, the everyday word for a branch of a tree. Fun fact: rama probably doesn't mean anything to you as an English speaker until you hear the word ramification and realize that they both come from the same Latin root ramus, which means—you guessed it—branch.

On the other hand, most Portuguese-speaking devs like to say branch in English, even though a tree branch would be a ramo (also galho) in Portuguese. Go figure!

When we say commit, push, and merge in English, we rarely think of them as both nouns and verbs; in English, it doesn't matter much. But in many languages, including our four, nouns and verbs have very different features. For example, nouns have grammatical gender, and verbs change form.

This creates another point of divergence between Spanish and Portuguese. In Spain, developers commonly put the Spanish verb hacer—"to do" or "to make"—in front of a plain English term: hacer commit, hacer push, and hacer un merge. To an English ear, they sound roughly like "make commit," "make push," and "make a merge."

But in Brazil, they prefer to say commitar and mergear , and then conjugate them as native Portuguese words: mergeei means "I merged," and mergeamos means "we merged." The English nouns have been swallowed whole by Portuguese grammar. Push took a third route: dar um push, literally "give a push."

Both languages are capable of borrowing words. Spanish speakers can turn the borrowed words into verbs, such as commitear , while Portuguese speakers can say fazer um commit—"make a commit." Both languages have the same linguistic tools. What differs is which forms their developer communities have collectively made sound natural.

Even when a term stays in English, the surrounding language quickly claims it. It gets an article, a grammatical gender, a plural, and sometimes a whole family of new verbs. For example, a pull request is feminine in Spanish: la pull request. In Portuguese, it's masculine: o pull request. There are also tricky choices. For example, Spanish devs are divided over the gender of...