How to translate quotations, code blocks, snippets and file excerpts within the documentation?

[tokideveloper]

In this issue, we want to solve the following problems:

• How to translate quotations?
  • Translate them?
  • Keep the original phrase next to the translation?
  • Add a translated (translation) note after the quotation, e.g. (Übersetzung) in German?
  • Which quotations marks to use?
• How to translate code blocks and snippets?
• How to translate file excerpts?

[tokideveloper]

How to translate quotations?

E.g. there are Twitter quotations of some prominent people on the home page. The key questions I have in mind are:

Translate them?

In my view: Yes, that's why translated pages shall exist! However, I'm not sure if there are legal restrictions whether translations are allowed or not.

Keep the original phrase next to the translation?

In my view: No, not necessary. The user may visit the official page in order to get the original phrase.

Add a translated (translation) note after the quotation, e.g. (Übersetzung) in German?

In my view: Yes, since ambiguous phrases could erroneously be translated wrongly and the user should have a chance to notice it.

Which quotations marks to use?

This depends on the target language and should be consistent within that language. The translators should find a solution for that in advance.

I'm not sure if there are other quotations within the Qubes website that have to be treated specially.

[tokideveloper]

How to translate quotations?

E.g. there are Twitter quotations of some prominent people on the home page. The key questions I have in mind are:

Translate them?

In my view: Yes, that's why translated pages shall exist! However, I'm not sure if there are legal restrictions whether translations are allowed or not.

Keep the original phrase next to the translation?

In my view: No, not necessary. The user may visit the official page in order to get the original phrase.

Add a translated (translation) note after the quotation, e.g. (Übersetzung) in German?

In my view: Yes, since ambiguous phrases could erroneously be translated wrongly and the user should have a chance to notice it.

Which quotations marks to use?

This depends on the target language and should be consistent within that language. The translators should find a solution for that in advance.

I'm not sure if there are other quotations within the Qubes website that have to be treated specially.

[andrewdavidwong]

Should be okay to translate quotations, but we definitely have to indicate that it's a translation of the original source's words and not an actual quotation from the original source. Putting the English original in parentheses next to the translation and adding (translation) next to the translation are both ways to achieve this. The former is safer but less likely to be useful to the reader. (Those who can read the original have no need for the translation.)

[andrewdavidwong]

Should be okay to translate quotations, but we definitely have to indicate that it's a translation of the original source's words and not an actual quotation from the original source. Putting the English original in parentheses next to the translation and adding (translation) next to the translation are both ways to achieve this. The former is safer but less likely to be useful to the reader. (Those who can read the original have no need for the translation.)

[tokideveloper]

I prefer the latter one since it's easier to read, so, summarizing it using an English-to-German example: Translate

"Hello world!"

with

„Hallo, Welt!“ (Übersetzung)

[tokideveloper]

I prefer the latter one since it's easier to read, so, summarizing it using an English-to-German example: Translate

"Hello world!"

with

„Hallo, Welt!“ (Übersetzung)

[tokideveloper]

How to translate code blocks and snippets?

An example from How to Create a BlackArch VM:

$ curl -O https://blackarch.org/strap.sh

# The SHA1 sum should match: 34b1a3698a4c971807fb1fe41463b9d25e1a4a09
$ sha1sum strap.sh

# Set execute bit
$ chmod +x strap.sh

# Run strap.sh
$ sudo ./strap.sh

Here, the line comments to sketch several steps should be translated in my view while the commands itself should stay untouched.

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

There could also be parts within comments that contain e.g. identifiers or other untranslatable things like strap.sh in the line comment # Run strap.sh in the example above. And these could be hard for translators to recognise.

A third thing: The following example from the USB docs contains two commands and the output of the first one:

[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi

The output is written in English. The big question is if it should be translated or remain untouched. If there exists only the English version of that command then keeping it English should be okay. However, if the command is localized for some other languages then it might be suitable to translate the output line(s) into those languages. One problem is that the translation done here could diverge from the translation of the official command project. But I think that's not a big one. The bigger problems are (1) to detect if there exists a localization of that command at all and (2) to detect untranslatable identifiers etc..

How to translate file excerpts?

Similar to the problems above is the problem whether file excerpts should be translated or not.
Translations could make it better to understand the structure of those files.
On the other hand, untranslated files can be matched character by character, making it easier to find a certain spot in that file (but this can also always be done by switching to our official English docs).
I'm not sure how to solve it.

[tokideveloper]

How to translate code blocks and snippets?

An example from How to Create a BlackArch VM:

$ curl -O https://blackarch.org/strap.sh

# The SHA1 sum should match: 34b1a3698a4c971807fb1fe41463b9d25e1a4a09
$ sha1sum strap.sh

# Set execute bit
$ chmod +x strap.sh

# Run strap.sh
$ sudo ./strap.sh

Here, the line comments to sketch several steps should be translated in my view while the commands itself should stay untouched.

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

There could also be parts within comments that contain e.g. identifiers or other untranslatable things like strap.sh in the line comment # Run strap.sh in the example above. And these could be hard for translators to recognise.

A third thing: The following example from the USB docs contains two commands and the output of the first one:

[user@dom0 ~]$ qvm-block
sys-usb:sda DataTraveler_2.0 () 246 MiB (attached to 'testvm' as 'xvdi')
[user@dom0 ~]$ sudo xl block-attach testvm phy:/dev/sda backend=sys-usb xvdi

The output is written in English. The big question is if it should be translated or remain untouched. If there exists only the English version of that command then keeping it English should be okay. However, if the command is localized for some other languages then it might be suitable to translate the output line(s) into those languages. One problem is that the translation done here could diverge from the translation of the official command project. But I think that's not a big one. The bigger problems are (1) to detect if there exists a localization of that command at all and (2) to detect untranslatable identifiers etc..

How to translate file excerpts?

Similar to the problems above is the problem whether file excerpts should be translated or not.
Translations could make it better to understand the structure of those files.
On the other hand, untranslated files can be matched character by character, making it easier to find a certain spot in that file (but this can also always be done by switching to our official English docs).
I'm not sure how to solve it.

[andrewdavidwong]

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

Correct. This example is poorly-written for precisely that reason.

There could also be parts within comments that contain e.g. identifiers or other untranslatable things like strap.sh in the line comment # Run strap.sh in the example above. And these could be hard for translators to recognise.

Yes. In general, it is difficult to translate a text that the translator does not understand.

The output is written in English. The big question is if it should be translated or remain untouched. If there exists only the English version of that command then keeping it English should be okay. However, if the command is localized for some other languages then it might be suitable to translate the output line(s) into those languages.

Agreed.

One problem is that the translation done here could diverge from the translation of the official command project.

It should not. It should be the actual verbatim output, just as with the English outputs.

Similar to the problems above is the problem whether file excerpts should be translated or not.
Translations could make it better to understand the structure of those files.
On the other hand, untranslated files can be matched character by character, making it easier to find a certain spot in that file (but this can also always be done by switching to our official English docs).
I'm not sure how to solve it.

Same as above. If the file itself is localized, use an actual excerpt from that localized file. If not, do not translate it (or provide a supplemental translation without replacing the original excerpt).

[andrewdavidwong]

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

Correct. This example is poorly-written for precisely that reason.

There could also be parts within comments that contain e.g. identifiers or other untranslatable things like strap.sh in the line comment # Run strap.sh in the example above. And these could be hard for translators to recognise.

Yes. In general, it is difficult to translate a text that the translator does not understand.

The output is written in English. The big question is if it should be translated or remain untouched. If there exists only the English version of that command then keeping it English should be okay. However, if the command is localized for some other languages then it might be suitable to translate the output line(s) into those languages.

Agreed.

One problem is that the translation done here could diverge from the translation of the official command project.

It should not. It should be the actual verbatim output, just as with the English outputs.

Similar to the problems above is the problem whether file excerpts should be translated or not.
Translations could make it better to understand the structure of those files.
On the other hand, untranslated files can be matched character by character, making it easier to find a certain spot in that file (but this can also always be done by switching to our official English docs).
I'm not sure how to solve it.

Same as above. If the file itself is localized, use an actual excerpt from that localized file. If not, do not translate it (or provide a supplemental translation without replacing the original excerpt).

[tokideveloper]

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

Correct. This example is poorly-written for precisely that reason.

I'm not sure what you want to say. Is it about my given example (which is indeed adversely chosen)?

There could also be parts within comments that contain e.g. identifiers or other untranslatable things like strap.sh in the line comment # Run strap.sh in the example above. And these could be hard for translators to recognise.

Yes. In general, it is difficult to translate a text that the translator does not understand.

Maybe, we could give this as an example in order to sensitize the translators for such exceptions. Additionally, we could offer help if a translator is unsure how to deal with it.

One problem is that the translation done here could diverge from the translation of the official command project.

It should not. It should be the actual verbatim output, just as with the English outputs.

I agree with you from an idealistic perspective. However, after thinking about it, I see several additional problems:

1. The outputs could be different between two different program versions. In order to resolve this, the translator has to know/find out the used program version (maybe tagged within the doc?) and install it in exactly that version.
2. The translator has to set up a appropriate environment (language settings, configs, VMs etc.).
3. The translator has to run the program (implies that he/she knows what he/she's doing) with the correct (translated) arguments and other (translated) input in order to produce the desired output.
4. The translator has to extract the output. This can be done by simply copying the terminal's screen (requires the error stream to remain empty or to accept error messages intentionally) but also by redirecting the output.
5. The output in the original text could be reduced to fewer but more important lines, thus, the translator has to figure out the corresponding lines and delete the rest.

Additional problems:

• Each step can be very hard to do and error-prone for an average translator IMHO.
• The second big problem here is that there could be programs the translators probably don't want to run, e.g. rm -rf /. (Here, the translator could dive into the source code in order to manually re-calculate the output for the translated input, but this is rather for the pros.)
• Last but not least, the input could be inaccessible or at least difficult to figure out (think of e.g. expired or revoked GPG keys).

In order to solve most of the mentioned problems, we could instruct and help the translators to get to the output step by step.

Similar to the problems above is the problem whether file excerpts should be translated or not.
Translations could make it better to understand the structure of those files.
On the other hand, untranslated files can be matched character by character, making it easier to find a certain spot in that file (but this can also always be done by switching to our official English docs).
I'm not sure how to solve it.

Same as above. If the file itself is localized, use an actual excerpt from that localized file. If not, do not translate it (or provide a supplemental translation without replacing the original excerpt).

I agree. Also, providing supplemental translation without replacing the original excerpt sounds like a feasible method in general.
This could also be a workaround for the problems above IMHO.

EDIT
I think, for most of the cases, the translator has to install Qubes in order to create the necessary environment. And since the problems above are likely easier for Qubes users, we could request the translators who also use Qubes to focus on such commands, file excerpts etc. in order to distribute man-power better.
END OF EDIT

[tokideveloper]

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

Correct. This example is poorly-written for precisely that reason.

I'm not sure what you want to say. Is it about my given example (which is indeed adversely chosen)?

There could also be parts within comments that contain e.g. identifiers or other untranslatable things like strap.sh in the line comment # Run strap.sh in the example above. And these could be hard for translators to recognise.

Yes. In general, it is difficult to translate a text that the translator does not understand.

Maybe, we could give this as an example in order to sensitize the translators for such exceptions. Additionally, we could offer help if a translator is unsure how to deal with it.

One problem is that the translation done here could diverge from the translation of the official command project.

It should not. It should be the actual verbatim output, just as with the English outputs.

I agree with you from an idealistic perspective. However, after thinking about it, I see several additional problems:

1. The outputs could be different between two different program versions. In order to resolve this, the translator has to know/find out the used program version (maybe tagged within the doc?) and install it in exactly that version.
2. The translator has to set up a appropriate environment (language settings, configs, VMs etc.).
3. The translator has to run the program (implies that he/she knows what he/she's doing) with the correct (translated) arguments and other (translated) input in order to produce the desired output.
4. The translator has to extract the output. This can be done by simply copying the terminal's screen (requires the error stream to remain empty or to accept error messages intentionally) but also by redirecting the output.
5. The output in the original text could be reduced to fewer but more important lines, thus, the translator has to figure out the corresponding lines and delete the rest.

Additional problems:

• Each step can be very hard to do and error-prone for an average translator IMHO.
• The second big problem here is that there could be programs the translators probably don't want to run, e.g. rm -rf /. (Here, the translator could dive into the source code in order to manually re-calculate the output for the translated input, but this is rather for the pros.)
• Last but not least, the input could be inaccessible or at least difficult to figure out (think of e.g. expired or revoked GPG keys).

In order to solve most of the mentioned problems, we could instruct and help the translators to get to the output step by step.

Similar to the problems above is the problem whether file excerpts should be translated or not.
Translations could make it better to understand the structure of those files.
On the other hand, untranslated files can be matched character by character, making it easier to find a certain spot in that file (but this can also always be done by switching to our official English docs).
I'm not sure how to solve it.

Same as above. If the file itself is localized, use an actual excerpt from that localized file. If not, do not translate it (or provide a supplemental translation without replacing the original excerpt).

I agree. Also, providing supplemental translation without replacing the original excerpt sounds like a feasible method in general.
This could also be a workaround for the problems above IMHO.

EDIT
I think, for most of the cases, the translator has to install Qubes in order to create the necessary environment. And since the problems above are likely easier for Qubes users, we could request the translators who also use Qubes to focus on such commands, file excerpts etc. in order to distribute man-power better.
END OF EDIT

[andrewdavidwong]

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

Correct. This example is poorly-written for precisely that reason.

I'm not sure what you want to say. Is it about my given example (which is indeed adversely chosen)?

I'm saying that the command-line example you quoted is poorly-written because it indicates non-root commands with an initial $ and comments with an initial #. The latter is ambiguous between a bash comment and a root prompt. The example should be rewritten to eliminate this ambiguity regardless of any translation concerns.

One problem is that the translation done here could diverge from the translation of the official command project.

It should not. It should be the actual verbatim output, just as with the English outputs.

I agree with you from an idealistic perspective. However, after thinking about it, I see several additional problems:

1. The outputs could be different between two different program versions. In order to resolve this, the translator has to know/find out the used program version (maybe tagged within the doc?) and install it in exactly that version.
2. The translator has to set up a appropriate environment (language settings, configs, VMs etc.).
3. The translator has to run the program (implies that he/she knows what he/she's doing) with the correct (translated) arguments and other (translated) input in order to produce the desired output.
4. The translator has to extract the output. This can be done by simply copying the terminal's screen (requires the error stream to remain empty or to accept error messages intentionally) but also by redirecting the output.
5. The output in the original text could be reduced to fewer but more important lines, thus, the translator has to figure out the corresponding lines and delete the rest.

Additional problems:

• Each step can be very hard to do and error-prone for an average translator IMHO.
• The second big problem here is that there could be programs the translators probably don't want to run, e.g. rm -rf /. (Here, the translator could dive into the source code in order to manually re-calculate the output for the translated input, but this is rather for the pros.)
• Last but not least, the input could be inaccessible or at least difficult to figure out (think of e.g. expired or revoked GPG keys).

Ok, then I think the actual English output should be provided along with the translation (if any).

[andrewdavidwong]

One problem I see is that it could be hard for a translator to determine whether a line starting with # belongs to a comment or a command executed by root (there are such prompts in our docs).

Correct. This example is poorly-written for precisely that reason.

I'm not sure what you want to say. Is it about my given example (which is indeed adversely chosen)?

I'm saying that the command-line example you quoted is poorly-written because it indicates non-root commands with an initial $ and comments with an initial #. The latter is ambiguous between a bash comment and a root prompt. The example should be rewritten to eliminate this ambiguity regardless of any translation concerns.

One problem is that the translation done here could diverge from the translation of the official command project.

It should not. It should be the actual verbatim output, just as with the English outputs.

I agree with you from an idealistic perspective. However, after thinking about it, I see several additional problems:

1. The outputs could be different between two different program versions. In order to resolve this, the translator has to know/find out the used program version (maybe tagged within the doc?) and install it in exactly that version.
2. The translator has to set up a appropriate environment (language settings, configs, VMs etc.).
3. The translator has to run the program (implies that he/she knows what he/she's doing) with the correct (translated) arguments and other (translated) input in order to produce the desired output.
4. The translator has to extract the output. This can be done by simply copying the terminal's screen (requires the error stream to remain empty or to accept error messages intentionally) but also by redirecting the output.
5. The output in the original text could be reduced to fewer but more important lines, thus, the translator has to figure out the corresponding lines and delete the rest.

Additional problems:

• Each step can be very hard to do and error-prone for an average translator IMHO.
• The second big problem here is that there could be programs the translators probably don't want to run, e.g. rm -rf /. (Here, the translator could dive into the source code in order to manually re-calculate the output for the translated input, but this is rather for the pros.)
• Last but not least, the input could be inaccessible or at least difficult to figure out (think of e.g. expired or revoked GPG keys).

Ok, then I think the actual English output should be provided along with the translation (if any).

[tokideveloper]

Concerning translating file excerpts

I played around with different ways of translating comments of file excerpts and formatting them. Here is the best way I could find::

In order to mark the original text visually, I propose to append #[original text] (with say five leading space characters and literal square brackets) to the end of each translated line.

Example for a file excerpt of /etc/sudoers.d/qubes, shown on the VM Sudo page, translated into German:

user ALL=(ALL) NOPASSWD: ALL

# Was zum Teufel?! Haben Sie den Verstand verloren?!     #[WTF?! Have you lost your mind?!]
#
# In Qubes VMs ergibt es keinen Sinn, das root-Konto vom Benutzerkonto getrennt     #[In Qubes VMs there is no point in isolating the root account from]
# zu halten. Das liegt daran, dass alle Benutzerdaten bereits vom Benutzerkonto     #[the user account. This is because all the user data is already]
# erreichbar sind, damit gibt es keinen unmittelbaren Vorteil für den Angreifer,     #[accessible from the user account, so there is no direct benefit for]
# wenn er sich bis zu root ausbreitet (Es gibt noch nicht einmal einen Vorteil     #[the attacker if she could escalate to root (there is even no benefit]
# beim Versuch, dauerhafte Rootkits zu installieren, weil Veränderungen am     #[in trying to install some persistent rootkits, as the VM's root]
# Wurzel-Dateisystem der VM bei jedem Start einer VM verlorengehen).     #[filesystem modifications are lost upon each start of a VM).]

This way,

• the formatting is quite easy to accomplish,
• the translated text can probably be read without using a horizontal scroll bar,
• the translated text is quite easy to read,
• the original text remains as desired and
• even the square brackets match up with the English language (in other languages, having text surrounded by square brackets could feel awkward).

For eager translators, I suggest them to justify the original text like this:

user ALL=(ALL) NOPASSWD: ALL

# Was zum Teufel?! Haben Sie den Verstand verloren?!                                 #[WTF?! Have you lost your mind?!]
#
# In Qubes VMs ergibt es keinen Sinn, das root-Konto vom Benutzerkonto getrennt      #[In Qubes VMs there is no point in isolating the root account from]
# zu halten. Das liegt daran, dass alle Benutzerdaten bereits vom Benutzerkonto      #[the user account. This is because all the user data is already]
# erreichbar sind, damit gibt es keinen unmittelbaren Vorteil für den Angreifer,     #[accessible from the user account, so there is no direct benefit for]
# wenn er sich bis zu root ausbreitet (Es gibt noch nicht einmal einen Vorteil       #[the attacker if she could escalate to root (there is even no benefit]
# beim Versuch, dauerhafte Rootkits zu installieren, weil Veränderungen am           #[in trying to install some persistent rootkits, as the VM's root]
# Wurzel-Dateisystem der VM bei jedem Start einer VM verlorengehen).                 #[filesystem modifications are lost upon each start of a VM).]

What do you think?

[tokideveloper]

Concerning translating file excerpts

I played around with different ways of translating comments of file excerpts and formatting them. Here is the best way I could find::

In order to mark the original text visually, I propose to append #[original text] (with say five leading space characters and literal square brackets) to the end of each translated line.

Example for a file excerpt of /etc/sudoers.d/qubes, shown on the VM Sudo page, translated into German:

user ALL=(ALL) NOPASSWD: ALL

# Was zum Teufel?! Haben Sie den Verstand verloren?!     #[WTF?! Have you lost your mind?!]
#
# In Qubes VMs ergibt es keinen Sinn, das root-Konto vom Benutzerkonto getrennt     #[In Qubes VMs there is no point in isolating the root account from]
# zu halten. Das liegt daran, dass alle Benutzerdaten bereits vom Benutzerkonto     #[the user account. This is because all the user data is already]
# erreichbar sind, damit gibt es keinen unmittelbaren Vorteil für den Angreifer,     #[accessible from the user account, so there is no direct benefit for]
# wenn er sich bis zu root ausbreitet (Es gibt noch nicht einmal einen Vorteil     #[the attacker if she could escalate to root (there is even no benefit]
# beim Versuch, dauerhafte Rootkits zu installieren, weil Veränderungen am     #[in trying to install some persistent rootkits, as the VM's root]
# Wurzel-Dateisystem der VM bei jedem Start einer VM verlorengehen).     #[filesystem modifications are lost upon each start of a VM).]

This way,

• the formatting is quite easy to accomplish,
• the translated text can probably be read without using a horizontal scroll bar,
• the translated text is quite easy to read,
• the original text remains as desired and
• even the square brackets match up with the English language (in other languages, having text surrounded by square brackets could feel awkward).

For eager translators, I suggest them to justify the original text like this:

user ALL=(ALL) NOPASSWD: ALL

# Was zum Teufel?! Haben Sie den Verstand verloren?!                                 #[WTF?! Have you lost your mind?!]
#
# In Qubes VMs ergibt es keinen Sinn, das root-Konto vom Benutzerkonto getrennt      #[In Qubes VMs there is no point in isolating the root account from]
# zu halten. Das liegt daran, dass alle Benutzerdaten bereits vom Benutzerkonto      #[the user account. This is because all the user data is already]
# erreichbar sind, damit gibt es keinen unmittelbaren Vorteil für den Angreifer,     #[accessible from the user account, so there is no direct benefit for]
# wenn er sich bis zu root ausbreitet (Es gibt noch nicht einmal einen Vorteil       #[the attacker if she could escalate to root (there is even no benefit]
# beim Versuch, dauerhafte Rootkits zu installieren, weil Veränderungen am           #[in trying to install some persistent rootkits, as the VM's root]
# Wurzel-Dateisystem der VM bei jedem Start einer VM verlorengehen).                 #[filesystem modifications are lost upon each start of a VM).]

What do you think?

[tokideveloper]

I'm saying that the command-line example you quoted is poorly-written because it indicates non-root commands with an initial $ and comments with an initial #. The latter is ambiguous between a bash comment and a root prompt. The example should be rewritten to eliminate this ambiguity regardless of any translation concerns.

Okay, I see. Thank you for clarification!

Concerning eliminating ambiguities, I'd suggest to add a Markdown convention rule for file excerpts and code snippets etc. in general in order to make it easier to distinguish, read and translate them. I'll create a new issue for that.

[tokideveloper]

I'm saying that the command-line example you quoted is poorly-written because it indicates non-root commands with an initial $ and comments with an initial #. The latter is ambiguous between a bash comment and a root prompt. The example should be rewritten to eliminate this ambiguity regardless of any translation concerns.

Okay, I see. Thank you for clarification!

Concerning eliminating ambiguities, I'd suggest to add a Markdown convention rule for file excerpts and code snippets etc. in general in order to make it easier to distinguish, read and translate them. I'll create a new issue for that.

[andrewdavidwong]

Concerning translating file excerpts

I played around with different ways of translating comments of file excerpts and formatting them. Here is the best way I could find::

In order to mark the original text visually, I propose to append #[original text] (with say five leading space characters and literal square brackets) to the end of each translated line.

Example for a file excerpt of /etc/sudoers.d/qubes, shown on the [VM Sudo][vmsudo] page, translated into German:

[...]

What do you think?

Sounds fine to me. No major problems immediately come to mind.

Concerning eliminating ambiguities, I'd suggest to add a Markdown convention rule for file excerpts and code snippets etc. in general in order to make it easier to distinguish, read and translate them. I'll create a new issue for that.

Good idea. Thanks.

[andrewdavidwong]

Concerning translating file excerpts

I played around with different ways of translating comments of file excerpts and formatting them. Here is the best way I could find::

In order to mark the original text visually, I propose to append #[original text] (with say five leading space characters and literal square brackets) to the end of each translated line.

Example for a file excerpt of /etc/sudoers.d/qubes, shown on the [VM Sudo][vmsudo] page, translated into German:

[...]

What do you think?

Sounds fine to me. No major problems immediately come to mind.

Concerning eliminating ambiguities, I'd suggest to add a Markdown convention rule for file excerpts and code snippets etc. in general in order to make it easier to distinguish, read and translate them. I'll create a new issue for that.

Good idea. Thanks.