Bureaucrats, cc_docs_admin, cc_staff
2,774
edits
Authoring guidelines: Difference between revisions
Jump to navigation
Jump to search
add section Code blocks are not translated
(advice to exclude code blocks from translation) |
(add section Code blocks are not translated) |
||
| Line 97: | Line 97: | ||
#In the “Priority languages” section, verify that “fr” or “en” appears as the priority language, that is, the language into which it needs to be translated. | #In the “Priority languages” section, verify that “fr” or “en” appears as the priority language, that is, the language into which it needs to be translated. | ||
#Click on “Mark this version for translation” | #Click on “Mark this version for translation” | ||
== Code blocks are not translated == | |||
Our professional human translator is not a programmer. | |||
They cannot distinguish between code and comments in every possible language, | |||
so the documentation team has instructed the translator to exclude code blocks from translation. | |||
Putting explanatory comments in code is excellent programming practice which we wish to encourage, | |||
but the value of the comments is decreased if the comments aren't translated. | |||
The documentation team has not found a solution for this that works in every case. | |||
Here are some suggestions: | |||
# Move the information contained in the comments outside the code block, into the surrounding text (which will then be translated). | |||
# Leave an index comment (e.g. "NOTE 1", "NOTE 2") to connect the external text to the relevant line of code. | |||
# If you're sufficiently bilingual, and familiar with the translation apparatus, you may translate the code block yourself. | |||
In summary: Please ''do not'' leave example code uncommmented, but please ''do'' remember that | |||
comments will not normally be translated, and consider how this will affect the understanding | |||
of the user reading the page in translation. | |||
= "Available software" page = <!--T:16--> | = "Available software" page = <!--T:16--> | ||