Question: What should be the translation of technical documentation and terms in it?
Hello, habracheloveki!
It is no secret that most technical documentation (guides, manuals, tutorials, API descriptions, etc.) in the world of web programming, and indeed IT, is in English. It is also not a secret that many Russian (and not only Russian) programmers do not speak English so that reading the texts on it is as easy as in their native language.
I see two ways out: either everyone polls to learn English to such an extent as not to notice the difference in which language you read, or translate documentation into Russian. And if the first one can be presented with difficulty, then with the translation of documentation, qualitative and not very much, everyone is surely familiar. This is what makes a quality translation different from a poor quality one and I want to know the opinion of Habronarod. But first, a little speculation about the issues of particular interest to me.
')
First of all, the question of the translation of terminology is of interest. It is clear that now no one will be translating the documentation for web developers to translate "browser" as "browser", and "server" as "servant", but here are many terms (I take, mostly, from the field of web frameworks) such as “view”, “helper”, “template”, “layout” in informal communication are often not translated at all, but traces from English are used (“view”, “helper”, etc.). About the fact that there are often ambiguities of translations and I don’t want to recall (view - view, display, presentation ...). But on the other hand, I personally am not very pleased to read the phrase “Helpers can be called directly in the context of a view — in templates, layouts, partials, or snippets.”
How do you think it is necessary to translate such terms in the documentation, especially intended for beginners in this field, or is it better to give tracing? And maybe even leave in English?
The second question - if you decide not to leave in English, then how to submit the translation and the original? Saw three main options:
Third - if you decide to leave the English original, is it worth it to translate? The options are the same, only mirrored: do not translate at all, translate (in brackets) only for the first time, translate each time
Another question - does it make sense to translate (in brackets) the names of classes, variables, files, etc., if they are found in the text? For example, “create a JobTable object” translate as “create a Job object.
Well, the last common question is the translation of abbreviations. We meet, say in the text the phrase “Use DRY (Don't Repeat Yorself) principle”, whether it should be translated as “Use the DRY principle (Don't Repeat Yorself - Don't repeat yourself)” or leave it as “Use the DRY principle (Don 't Repeat Yorself) “?
Well, a couple of specific questions about the translation of terms: "View" (from the MVC architecture) - view, display, presentation - which translation do you think is more appropriate? Or is there an option? And, similarly, “layout” - breakdown, layout, layout, something else?
And I was inspired to write my first topic on Habré as follows: I decided to master various php frameworks here and faced the problem of the lack (or insufficiency or obsolescence) of Russian documentation. I have to read English, but apparently, blogs have started mod writing technical documentation with elements of the spoken language - jokes, slang, etc., which presents some difficulties for me (I always wrote “technical English - read fluently in questionnaires and summaries”) , it takes a lot of time to translate unusual words and expressions, and even in the context of studying the framework itself.
So I thought that if I recorded my torments with dictionaries and Google, that is, what I translate “in my head”, “into a file,” then I’ll raise the level of understanding of the text (it’s not tempting to assume that I understood the words from the context correctly), and the level of English, well, that someone my translations, if you put them somewhere, will facilitate familiarity with one or another product. But I ran into the problem of translating terms. Personally, I am pleased to read translations like “That's why the view is divided into layout (layout) and template (template). Layout is usually common to the entire application or group of pages. “And you would no matter what the translation of the phrase„ That's why the view is separated. The layout is usually global to the application, or would you like to see in Russian?
It is no secret that most technical documentation (guides, manuals, tutorials, API descriptions, etc.) in the world of web programming, and indeed IT, is in English. It is also not a secret that many Russian (and not only Russian) programmers do not speak English so that reading the texts on it is as easy as in their native language.
I see two ways out: either everyone polls to learn English to such an extent as not to notice the difference in which language you read, or translate documentation into Russian. And if the first one can be presented with difficulty, then with the translation of documentation, qualitative and not very much, everyone is surely familiar. This is what makes a quality translation different from a poor quality one and I want to know the opinion of Habronarod. But first, a little speculation about the issues of particular interest to me.
')
First of all, the question of the translation of terminology is of interest. It is clear that now no one will be translating the documentation for web developers to translate "browser" as "browser", and "server" as "servant", but here are many terms (I take, mostly, from the field of web frameworks) such as “view”, “helper”, “template”, “layout” in informal communication are often not translated at all, but traces from English are used (“view”, “helper”, etc.). About the fact that there are often ambiguities of translations and I don’t want to recall (view - view, display, presentation ...). But on the other hand, I personally am not very pleased to read the phrase “Helpers can be called directly in the context of a view — in templates, layouts, partials, or snippets.”
How do you think it is necessary to translate such terms in the documentation, especially intended for beginners in this field, or is it better to give tracing? And maybe even leave in English?
The second question - if you decide not to leave in English, then how to submit the translation and the original? Saw three main options:
- Do not specify the original term.
- When you first use the text (sometimes the head) to write "helper (helper)" or "helper (helper)", and then use only the translation
- Write "helper)" at every use of the term in the text
Third - if you decide to leave the English original, is it worth it to translate? The options are the same, only mirrored: do not translate at all, translate (in brackets) only for the first time, translate each time
Another question - does it make sense to translate (in brackets) the names of classes, variables, files, etc., if they are found in the text? For example, “create a JobTable object” translate as “create a Job object.
Well, the last common question is the translation of abbreviations. We meet, say in the text the phrase “Use DRY (Don't Repeat Yorself) principle”, whether it should be translated as “Use the DRY principle (Don't Repeat Yorself - Don't repeat yourself)” or leave it as “Use the DRY principle (Don 't Repeat Yorself) “?
Well, a couple of specific questions about the translation of terms: "View" (from the MVC architecture) - view, display, presentation - which translation do you think is more appropriate? Or is there an option? And, similarly, “layout” - breakdown, layout, layout, something else?
And I was inspired to write my first topic on Habré as follows: I decided to master various php frameworks here and faced the problem of the lack (or insufficiency or obsolescence) of Russian documentation. I have to read English, but apparently, blogs have started mod writing technical documentation with elements of the spoken language - jokes, slang, etc., which presents some difficulties for me (I always wrote “technical English - read fluently in questionnaires and summaries”) , it takes a lot of time to translate unusual words and expressions, and even in the context of studying the framework itself.
So I thought that if I recorded my torments with dictionaries and Google, that is, what I translate “in my head”, “into a file,” then I’ll raise the level of understanding of the text (it’s not tempting to assume that I understood the words from the context correctly), and the level of English, well, that someone my translations, if you put them somewhere, will facilitate familiarity with one or another product. But I ran into the problem of translating terms. Personally, I am pleased to read translations like “That's why the view is divided into layout (layout) and template (template). Layout is usually common to the entire application or group of pages. “And you would no matter what the translation of the phrase„ That's why the view is separated. The layout is usually global to the application, or would you like to see in Russian?
Source: https://habr.com/ru/post/48499/
All Articles