From experience translating style guides

Hello, dear habrozhitel! I would like to bring to your attention the experience of translating a code style style guide that is well-known among Ruby developers . The original text of this guide is compiled by the Ruby community of programmers under the creative guidance of Bozhidar Batsov .

It may seem to many of you that translating an English-language programming resource is a thankless waste of time, because most developers are fluent in English. However, we had a fairly clear motivation: to thoroughly familiarize ourselves with the established practices of designing a code for Ruby. And in the translation process you have to read the text twice, if not three times.

In addition to this purely flickering foundation, we believed that the development of terminology would simplify technical communication in our native language (there is a simple answer “why!” To the question “why?”), And it will also make it easier for those who find it easier to read this resource in Russian.

The initial translation was made in a copy (fork) of the main project on Github, after which, as changes accumulated in the basic (upstream) version, amendments were made to the translation on a regular basis. There are several noteworthy moments in this process:

* Changes from the base version are transferred using diff and patch , since the structure of both projects is slightly different:

$ git fetch bbatsov
$ git diff master:README-enUS.md bbatsov/master:README.md > patch.diff
$ patch README-enUS.md patch.diff

* Changes in the English version are more convenient to view in the form of a difference before and after merging with the basic version:

$ git difftool  master@{1} master -t meld

Using graphical tools like meld makes comparison easier with color highlighting.

The main difficulty (however, as in any similar translation project) is the translation of terminology and its maintenance in a uniform state. The scope of the project allows you to do without translation memory systems and maintain a simple glossary. Unfortunately, in many issues there is still no established option. Searching for translated subject literature and discussion with project participants is a sound decision in this case.

If you want to participate, then join the project ! We welcome any constructive criticism.

Also popular now: