Discussion: Localize code comments

[Rick-Anderson]

Leave a comment here if you would like to have code comments in your native language. Include a link to the document that includes code with English only comments.

THIS IS NOT AN ISSUE TO ADD NEW LANGUAGES, IT'S TO LOCALIZE THE CODE COMMENTS WITHIN THE CODE IN ADDITION TO THE DOCUMENT.

[renepanke]

How to use anonymous pipes for local interprocess communication

I'd love to read this in german :)

[RiadKatby]

https://docs.microsoft.com/en-us/aspnet/core/fundamentals/localization?view=aspnetcore-3.1 It would be helpfull to see that link in Arabic

[JasonCard]

@RiadKatby Thank you for your feedback. We currently do not localize this content into Arabic, but will keep your feedback in mind for future consideration.

[edenalencar]

I would like that comments were in Brazilian Portuguese!

[lindexi]

https://docs.microsoft.com/zh-CN/dotnet/standard/io/memory-mapped-files

I'd love to read this in Chinese

[SetTrend]

My opinion may not be PC, but does this make sense anyway? Many of the documentation pages are automatically (and, thus, often wrong) translated. So, is this question about having comments automatically translated, too? How about text in code then (e.g. Console.WriteLine("Hallo, Welt!");, myButton.Text = "Ergebnis anzeigen";)?

[wpqs]

I share SetTrend's concern, does it make any sense to provide code comments in anything other than English?

Most developers I know prefer to let the code speak for itself, so rather than adding a comment they would try to re-write the code in a way that makes its intent clearer. Accordingly there is an argument that code comments should be added only as a last resort to explain something that is truly complex from which it follows that the comment itself is unlikely to be trivial. Translating such comments into other languages is likely to be a challenging task that will be difficult to automate, so I suspect a team of people will be needed who are a) knowledgeable enough technically to understand the comment in the context of the code b) knowledgeable enough about both languages to provide a fair translation. In fact it could be argued that only the author of the code should write the comment in the first place. Therefore perhaps the real question is whether or not we should encourage programmers to write comments in their mother tongue? That raises its own problems. What would people feel about code comments written in Welsh, say?

My view is that writing comments in anything other than English makes the code accessible to far fewer people. The world of scientific publications has a similar issues. If you want your paper to be widely read and cited, then it has to be written in English. This is certainly unfair to people whose mother tongue isn't English, but is the price we must pay for being able to disseminate knowledge globally.

I urge caution before embarking on a project to provide code comments in languages other than English as there is a danger that the result would be an unintelligible mess that was useful to nobody, particularly in the case of files edited by multiple developers.

[EpsilonBoo]

Although i'm from germany i prefer to read comments in English. The same goes for help in general. The problem is that many technical terms are localized but the original term was founded in english. Sometimes it's difficult to understand what is really meant if to much is localized.

[Rick-Anderson]

@SetTrend and @wpqs we're looking for comments from non english speakers.

How about text in code then (e.g. Console.WriteLine("Hallo, Welt!");, myButton.Text = "Ergebnis anzeigen";)?

Only code comments would be localized.

@wpqs

Translating such comments into other languages is likely to be a challenging task that will be difficult to automate,

It's automated, just as the majority of the documents are machine translated.

My view is that writing comments in anything other than English makes the code accessible to far fewer people.

Why is that, the /en.en/ version has the doc in the original english and the comments in the original english. All the english text is translated in a doc, why do you think it will make the doc worse to also translate the code comments?

@wpqs Please rewrite the following snippets so comments aren't beneficial

• The 2nd sample: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/routing?view=aspnetcore-3.1#aspnet-core-endpoint-definition-1
• https://docs.microsoft.com/en-us/dotnet/standard/io/pipelines

[Rick-Anderson]

@EpsilonBoo

Although i'm from germany i prefer to read comments in English. The same goes for help in general.

A colleague in Germany tells me he first reads the German version, and if it's not clear he reads the /en.en/ version. So you lose nothing by comments localized.

The problem is that many technical terms are localized but the original term was founded in english.

We have two mechanisms to prevent technical terms from being localized. An issue should be opened when that's not the case.

Sometimes it's difficult to understand what is really meant if to much is localized.

You have the option to drop back to /en.en/, most folks don't have that option.

[SetTrend]

@Rick-Anderson : I'm German, too. (Please refer to my GitHub profile). I humbly take this as a compliment 😉

Here's just one example of a hard-to-understand translation:

Original English Version

It's not unusual to use dependency injection in a chained fashion. Each requested dependency in turn requests its own dependencies. The container resolves the dependencies in the graph and returns the fully resolved service. The collective set of dependencies that must be resolved is typically referred to as a dependency tree, dependency graph, or object graph.

Translated German Version (hard to grasp)

Die Abhängigkeitsinjektion wird häufig als Verkettung verwendet. Jede angeforderte Abhängigkeit fordert wiederum ihre eigenen Abhängigkeiten an. Der Container löst die Abhängigkeiten im Diagramm auf und gibt den vollständig aufgelösten Dienst zurück. Die gesammelten aufzulösenden Abhängigkeiten werden als Abhängigkeitsstruktur, Abhängigkeitsdiagramm oder Objektdiagramm bezeichnet.

English Version, Translated From German (utilizing Bing)

Dependency injection is often used as a concatenation. Each requested dependency, in turn, requests its own dependencies. The container resolves the dependencies in the diagram and returns the fully resolved service. The collected dependencies are called dependency structure, dependency diagram, or object diagram.

The following doesn't make sense in German:

The heading text in the screenshot reads: "The preceding command displays the following dialog:"

But, no, it doesn't "display the following dialog". Because with a German Windows installation (which German users, like me, will most likely use) it'll rather resemble this:

May I ask what you expect to be the benefit from only translating code comments?

Currently, I don't see any benefit from using German comments but English variable names, like in this UWP example (try to relate the comments to the code):

Compositor _compositor;
ContainerVisual _container;
SpriteVisual _colorVisual1, _colorVisual2;
CompositionColorBrush _blackBrush, _greenBrush;

// Quadrat mit Hilfe eines zusammengesetzten Pinsels erstellen
_compositor = Window.Current.Compositor;
_container = _compositor.CreateContainerVisual();

// Ersten Farbpinsel in der Farbe schwarz erstellen
_blackBrush = _compositor.CreateColorBrush(Colors.Black);
_colorVisual1= _compositor.CreateSpriteVisual();
_colorVisual1.Brush = _blackBrush;
_colorVisual1.Size = new Vector2(156, 156);
_colorVisual1.Offset = new Vector3(0, 0, 0);
_container.Children.InsertAtBottom(_colorVisual1);

// Zweiten, kleineren Farbpinsel in der Farbe grün erstellen und in der Mitte zentrieren
_ greenBrush = _compositor.CreateColorBrush(Color.FromArgb(0xff, 0x9A, 0xCD, 0x32));
_colorVisual2 = _compositor.CreateSpriteVisual();
_colorVisual2.Brush = _greenBrush;
_colorVisual2.Size = new Vector2(150, 150);
_colorVisual2.Offset = new Vector3(3, 3, 0);
_container.Children.InsertAtBottom(_colorVisual2);

I tend to consent to @EpsilonBoo's comment: For foreign readers it's impossible to relate native comments to English variable names, literal texts or similar.

[Rick-Anderson]

@SetTrend you don't see any code comments that could be beneficial to non-native speakers?

[SetTrend]

You see, all the different .NET class names, fields, properties, methods, variable names - and, basically, all technical terms are commonly given in English. If someone wouldn't be able to tell the meaning of InsertAtBottom() because of her lack of English speaking skills, there wouldn't be a benefit in commenting these foreign terms.

Let me give a C# pseudo code example that's supposed to put you in a foreign reader's shoes:

排序 _排序;
容器视觉 _容器;
雪碧视觉 _颜色视觉1, _颜色视觉2;
组合颜色刷 _黑刷, _格林布什;

// Create square using composition color brushes
_排序 = 窗口.当前.排序;
_容器 = _排序.创建容器视觉();

// Create first color brush using a black square shape
_黑刷 = _排序.创建颜色刷(颜色.黑);
_颜色视觉1= _排序.创建特权视觉();
_颜色视觉1.刷 = _黑刷;
_颜色视觉1.大小 = 新增功能 向量2(156, 156);
_颜色视觉1.抵消 = 新增功能 向量3(0, 0, 0);
_容器.孩子.插入底部(_颜色视觉1);

// Create second color brush using a smaller green square shape and center it within first color brush
_格林布什 = _排序.创建颜色刷(颜色.从颜色(0xff, 0x9A, 0xCD, 0x32));
_颜色视觉2 = _排序.创建特权视觉();
_颜色视觉2.刷 = _格林布什;
_颜色视觉2.大小 = 新增功能 向量2(150, 150);
_颜色视觉2.抵消 = 新增功能 向量3(3, 3, 0);
_容器.孩子.插入底部(_颜色视觉2);

As you can see from my example, localizing only the comments doesn't help in understanding the code.

So, from my perspective, the reader either knows a fair amount of the English language or he/she is lost anyway.

I believe it's perfectly alright to provide localized documentation (given it'd be correct and not as tainted as it currently is) to give native readers a thorough understanding of a topic. Hoever, when it comes to coding, a small set of English speaking knowledge is inevitable.

Actually, back in the past, when I gave programming courses, I used German class and variable names for the learner to be able to easily tell (English) framework classes, typedefs etc. from my (German) proprietary example terms. Today, when I create examples, I prefix all my classes, typedefs, events etc. with "My", so the reader can immediately distinguish my types (which she doesn't need to remember) from types provided by the framework (which she needs to learn and remember).

[Rick-Anderson]

@SetTrend Please rewrite the following snippets so comments aren't beneficial

https://docs.microsoft.com/en-us/dotnet/standard/io/pipelines

I've been told by several localized comments would be beneficial.

You see, all the different .NET class names, fields, properties, methods, variable names - and, basically, all technical terms are commonly given in English. If someone wouldn't be able to tell the meaning of InsertAtBottom() because of her lack of English speaking skills, there wouldn't be a benefit in commenting these foreign terms.

All those items would not be localized

So, from my perspective, the reader either knows a fair amount of the English language or he/she is lost anyway.

that's not our experience

[EpsilonBoo]

I think it is ok to localize help items and code comments. There are for sure people who would benefit from. But nevertheless automatic translation en-de is from my point of view not so nice to read. @SetTrend : Nice example: EN="dependency injection" -> DE="Abhängigkeitsinjektion " This kind of technical terms are uncomfortable to read if localized. @Rick-Anderson : But you are right. I'm free to switch back to original english version. Therefore it could only be helpful for other people to have the localized version.

[SetTrend]

@Rick-Anderson:

When I follow the hyperlink you suggested, I get a 404 File Not Found error, I'm afraid.

I've been told by several localized comments would be beneficial.

Did these people explain why localized comments would be beneficial? I feel the "why" is the important part to know here, to then derive particular conclusions from.

All those items would not be localized

Exactly. If the (localized) documentation itself wasn't conclusive enough to clarify the purpose of (English) class names and objects, then why should an example be?

It's not the purpose of examples to add further information to documentation. The purpose of examples is to reflect in the shortest possible manner what's been described in the documentation, so the reader get's a first feeling of the class and won't feel alone when for the first time trying to implement what's been described in the documentation.

that's not our experience

If your experience is different, I'll gladly refrain from my position.

However, how can comments alone be helpful when string literals, conveying the result of an example, won't be translated, too?

I'm currently reading through the UWP documentation. Here's an example of C# code with string literals which, when executed, reflect the status of an adaptive audio input stream. The string literals merely reword the status enum.

Would you be striving for adding a localized comment for foreign readers to each of the status cases to finally clarify what's happening (which is the exact purpose of the string literals in the example)?

@EpsilonBoo:

Fine observation.

Yet, it's not only the half-baked translation of technical terms (in German we don't have this kind of technical term. Moreover, "Injektion" is Latin, not German. A rather more correct translation into German would be "Das Einbringen von Abhängigkeiten", which is three words instead of two in English, still easy to grasp/read. [We Germans tend to prefer "verb derived noun of attribute" over "attribute _ verb derived noun" which, in contrast, English speakers prefer.])

In my example I was rather referring to misleading/wrong translations:

• used in a chained fashion → used as a concatenation
• graph → diagram
• collective set of dependencies → collected dependencies
• tree → structure
• ...

[Rick-Anderson]

https://docs.microsoft.com/en-us/dotnet/standard/io/pipelines

[SetTrend]

@Rick-Anderson:

Nice article.

You requested me to survey the above page for a necessity of localizing comments. So these are my (personal) remarks on first sight (sorted by reading sequence order):

1. The following code is typical for a TCP server that receives line-delimited messages (delimited by '\n') from a client:

   I humbly doubt this is a "typical" real-life implementation:

   The function name ProcessLinesAsync claims to process multiple lines while the code itself only processes a single line ProcessLine. No loop, no continuation/EOF logic whatsoever.

   Alternatively, I propose to rather have written something similar to this:

   async Task ProcessLinesAsync(NetworkStream stream)
   {
    bool eof = false;
   
    do
    {
       var buffer = new byte[1024];
   
       eof = await stream.ReadAsync(buffer, 0, buffer.Length) < buffer.Length;
       await ProcessLineAsync(buffer);
   
    } while (!eof);
   }
   

   Anyway, along with the subsequent bullet list from the page the existing snippet is simple, concise and clear in its statement, conveying existing issues when processing streams.

   
   

2. The following code addresses some of these problems:

   The purpose of this page is to teach how to process streams using "System.IO.Pipelines in .NET". It's purpose is not to teach how to manually handle this task and avoiding to use System.IO.Pipelines.

   So, the subsequent, huge example code is not adding value to the page. Hence, it's redundant, and I propose it to be removed.

   
   

3. The xref:System.IO.Pipelines.Pipe class can be used [...]

   I conclude from this snippet of the sentence that using System.IO.Pipelines.Pipe is optional when utilizing PipeWriter and PipeReader. But I'm not sure, though.

   If it's mandatory to use Pipe, I propose to rephrase that sentence like this: "Use the Pipe class to [...]"

   
   

4. The subsequent example that's supposed to show how to utilize Pipe, PipeWriter and PipeReader comprises of not less than 90 lines of code, 90 % of these lines are not even dealing with any of these three classes at all.

   I propose to shrink this example to less than 10 lines of code. The example is not supposed to teach exception handling, logging or anything else. It's purpose is to merely give a brief impression of how to apply these three classes.

   Actually, after examining that example I'm not sure if Pipe, PipeWriter and PipeReader are actually beneficial at all. I don't see any significant savings when there's so much manual buffer manipulation required. Moreover, PipeWriter and PipeReader don't deal with IBuffer or other CLR kinds of memory buffer pointers.

   From my purely personal point of view it's a waste to implement three distinct classes just to provide a simple FIFO buffer mechanism translating a socket's buffer list into a continuous stream of bytes. For such kind of designated pipe I would have rather provided something similar to this:

   public class SocketPipe : IDisposable
   {
      // private fields
      private Socket _socket;
      private byte[] _delimTriggerSequence;
      private int _fillLevel, _maxFillLevel;
      private Action<byte[]> _onTriggerSequenceReceived;
      private Action<byte[]> _onMaximumFillLevelReached;
   
      // public properties
      public int FillLevel => _fillLevel;
   
      // public constructors
      public SocketPipe(Socket socket) { ... }
   
      // public methods  -- I'm using callbacks here instead of events for brevity
      public void Open(byte[] delimTriggerSequence, Action<byte[] buffer> onTriggerSequenceReceived) { ... }
      public void Open(int maxFillLevel, Action<byte[] buffer> onMaximumFillLevelReached) { ... }
   
      public byte[] GetUnreadData() { ... }
   
      public void Close() { ... }
      public void Dispose() => Close();
   
      ...
   }
   

   Any consumer then would simply need to call something resembling this:

   System.Net.Sockets.Socket mySocket = System.Net.Sockets.Socket(...);
   SocketPipe pipe = new SocketPipe(mySocket).Open(new byte[] { 0x0a }, buffer =>
   {
      ProcessLine(buffer);
   });
   

   
   

5. There are two loops:

   You're extensively explaining the preceding code example here. Why do you believe there's a requirement for having comments in code, too?

   The code comments don't add value to the information. They just double what you're already explaining here.

I'll stop my observation here. Hope this is of any help to you.

Looking forward to your thoughts.

[listenuptome]

https://docs.microsoft.com/ru-ru/aspnet/core/fundamentals/routing?view=aspnetcore-3.1 russian please.

[sebastienbages]

Hello World :) https://docs.microsoft.com/fr-fr/aspnet/core/fundamentals/routing?view=aspnetcore-3.1#endpoint French please

[karaok1]

If it is going to be machine translated, that would be more harm than good. In my experience at least, it is horrific at translating Turkish and overcomplicates articles.

[maskym]

Most of the time, I have a result in my native language and the original in english : I understand better the english version. The translated article is so bad that I don't understand it... I often use Deepl translator as I think its translations are very good but as it's not a Microsoft product I doubt the documentation could be translated with Deepl.

[tudor-turcu]

While this might be useful to a beginner (school students learning .NET), it's worth doing only if Microsoft has the resources and qualified people for such a translation. Otherwise, any developer with a little experience already knows English well enough.

[ldmrgrc]

https://docs.microsoft.com/es-es/aspnet/core/data/ef-rp/update-related-data?view=aspnetcore-5.0 It would be nice to see that tutorial in Spanisth too. Thanks

[RickAndMSFT]

https://docs.microsoft.com/es-es/aspnet/core/data/ef-rp/update-related-data?view=aspnetcore-5.0 It would be nice to see that tutorial in Spanisth too. Thanks

It is in Spanish, via the /es-es/

[mahdisky]

I'd love to read this in Persian :)

[Harmyder]

Hebrew and Ukrainian, please

[klenium]

Auto translated pages are so bad I can't understand them even when I face a totally new API/technology/etc. I had no idea what it's talking about. Some weeks ago I installed FFS MSDN in English to disallow this stupid forced auto translator, since no matter how many times I changed my settings, it always reenabled auto translations.

[RHRafi009]

https://docs.microsoft.com/en-us/aspnet/core/security/authentication/?view=aspnetcore-6.0 In Bangla

[sogeisetsu]

https://docs.microsoft.com/zh-cn/dotnet/standard/io/how-to-copy-directories

IN Chinese