MariJ
With a strong linguistic education, MariJ is the translation coordinator at Plan ₿ Network. She helps people understand how Bitcoin works, and how to create fluid and easy-to-understand content!
adoptiongood-practiceuser-friendly
Welcome to this tutorial about the guidelines to follow when proofreading content on Plan ₿ Academy. We are glad you share our mission to translate Bitcoin materials in as many languages as possible, in order to help people gain awareness about how it works and how it can be used in their daily lives.
First of all, contributing to Plan ₿ Academy public repository gives you the chance to write tutorials, proofread the existing content, or even propose the addition of a new language to the platform. To know more, join our Telegram Group first, and write a brief presentation about you and the languages you can speak.
The present tutorial is dedicated to contributors who want to proofread content. Most of them don't know much about Github or the Markdown language we use inside the repository, so it's important to share some insights on the key factors involved in this task.
Here below, I gathered the most common issues that proofreaders encounter. Feel free to suggest more, as it can help others improve.
Before diving into the specifics, the first thing to do is read this tutorial on the practical actions to follow on Github, by forking Plan ₿ Academy repository, committing changes and sending PRs:
What is proofreading?
Proofreading is the final review process of a written text, to identify and correct errors in grammar, spelling, punctuation, and formatting. It ensures the text is clear, coherent, and free of mistakes before publication or submission.
When you undergo this type of task, it's important to follow the meaning of the original language (EN or FR), but make sure the text in the final language is as fluid as possible for a native speaker.
Always remember that translation/proofreading is EDUCATION!
In fact, our shared goal is to educate as many people as possible on Bitcoin, so it is fundamental that the material they read is smooth and clear.
In this sense, all contributors on Plan ₿ Academy are educators!
The first steps before proofreading on Plan ₿ Academy
Before starting a new proofreading task, announce it in the Telegram group or inform your Plan ₿ Academy coordinator, who will open a dedicated issue. When you receive the issue link, simply comment that you are starting with the proofreading task of that content.
This system helps the coordinator keep track of the progress inside the repo, and it allows the content to be "claimed" by the proofreader, preventing duplicate efforts by someone else.
On the issue itself, you will find the links that redirect you to the content to check. You can simply click on them, or, even better, you can go back to your own forked repo and work directly from there. Let's see how you can do it!
First of all, ALWAYS remember to SYNC your repo, on the "dev" branch. This way, the content will always be updated before you start any type of task, and you will not create any conflicts between old and new material. Make sure to click on "Sync fork" and "Update branch".
After successfully syncing, you can directly access the content of interest and commit on a new branch, as shown in this tutorial. Otherwise, you can open a new branch where to work, by clicking on "Branches", like shown below.
Inside this new page, you will find all the branches you already opened under the title "Your Branches". This section is very useful because it allows you to easily find where you modified some content. If you want to open a new branch, you can click on "New Branch" on the upper right corner of the page.
Then, you will get a pop-up where you need to insert the name of the new branch. In the case below, I chose to call it "BTC101-FR". This way, I will always remember that this specific branch needs to be used for the proofreading of the course BTC101 in French, and I will not use it for any other task.
I suggest you do the same: make sure to open a new branch anytime you need to start a new task.
After creating this new branch, make sure to click on it from "Your Branches" in the previous page and start working on the .md file related to the specific content (in my case, I will click on "courses" -> "BTC101" -> "fr.md"). All commits related to the specific file will have to be committed (saved) inside the same branch.
Original language or translation?
When doing some proofreading of content, it's important to always check the original English (or French) version of it. Be aware that we translate using AI language tools, so the rendering in the target language might not be fluid or well understandable for the final reader.
Thus, feel free to make adjustments to the text and modify sentences, if needed. Our objective is to enhance fluidity, but always following the original meaning. In case of doubts about how to treat a specific word, make sure to ask the translation coordinator.
LLM tools may translate some words related to Bitcoin literally, like Lightning Network. It is especially the case when it deals with very technical words. In cases like these, it is advisable to maintain the original English word in your target language for better clarity, unless your language rules impose you to translate every single word.
In this second case, always do some research to see if someone else in your Bitcoin community has already translated that word and it is now broadly used.
-
One solution could be to check on BitcoinWiki in your target language to see if the word was translated or not. If it's not, you keep the word in English.
-
In any case, my advice would be to insert the EN word nonetheless, adding the corresponding meaning in the target language inside round parenthesis, following the scheme EN (LANG), or vice-versa. Ex. Address (indirizzo), or indirizzo (address).
-
Another good solution is to keep the EN original word/phrase, then create a hyperlink that redirects to the glossary on planb.network. To do this, you need to insert the word/phrase inside square brackets, and the link inside round parenthesis, like you can see in the example below:
[UTXO](https://planb.academy/resources/glossary/utxo)
In the final result (image below) you will not visualize the entire link, and the word will become clickable.
Please note that the glossary link you will take from the website contains the language code after the word "network" (example:
https://planb.academy/en/resources/glossary/utxo-> here you can read the language code "en"). In this case, remove the language code from the link, like you saw in the box above. This way, the system will automatically take the reader to their designated language.The content on the repository is full of hyperlinks like these above. Now that you know what they mean, make sure not to delete any link inserted by the original author.
-
Another thing related to word rendering is the following. If you find "Plan ₿ Academy" in the text, leave it in this original form. Do not translate the word "plan" or the word "network". Besides, do NOT use the article "The" when introducing Plan ₿ Academy: consider it as a brand.
-
The same goes for "₿-CERT", "BIZ SCHOOL", "TECH SCHOOL", which should also be kept in the original form.
One final note to this paragraph: as we said above, we use AI tools to translate content, and then we ask for contributors' intervention to make sure everything is fluid and well proofread.
If you use AI to proofread the majority of the text, we will sure notice, as we are familiar with the typical sentence structures that AI generates. If we find that you relied solely on AI for proofreading, without applying significant changes, the final reward in sats may be reduced by half!
The structure of headers
In the markdown language, headers (and paragraph titles) all begin with the hash sign
#. The number of hash signs corresponds to the heading level. For example, a heading of level three has three number signs before the text (e.g., ### My Header).In courses, the most important parts are introduced by one single hash sign, while the sub-parts can have from two to four hash signs. In tutorials, we normally only use headers with two hash signs.
Make sure to NEVER delete hash signs before a title, otherwise you will create issues with the structure of the text.
At the same time, don't change the chapterID part you can see in the image above,
<chapterId>d668fdf6-fb4c-4bbf-82e1-afcb95c122e0</chapterId> or the video references like :::video id=ba99951f-81d2-418f-b5e7-4b8c9f8b8cc8:::.When we insert
# before a title, it will automatically become bold in the course preview, so avoid making the titles bold during correction.As a side note, in the EN version of courses, the titles introduced by one or two
# have all the words starting in capital letters, while titles starting with three or four #, usually don't follow this rule. If possible, make sure that the titles in your target language follow this structure.The initial section of courses
At the beginning of any content, you will find the following static lowercase words: "name", "description", "objectives". They are used by the website to decode the content itself and are always left in EN. As a consequence, DO NOT translate them, otherwise the content will create synchronization issues. Make sure to only proofread the part after the colon, which is automatically translated by AI.
In this same initial section, keep the format as it is. Don't add anything at the beginning of the text. E.g., avoid adding "tt" before the dashes, like in the image below!
How to deal with course images
Our website now features translated images for nearly every course!
When you proofread, always verify that all images are present and displayed correctly. In the
code view, if you find this sort of line , it means that an image will be displayed there.Make sure you always add a new line between the image code and the text. An example below:
WRONG CONFIGURATION: - to start translating, click on the button `Translate`:  To save, click on `save`! RIGHT CONFIGURATION: - to start translating, click on the button `Translate`:  To save, click on `save`!
Besides, remember to read the content of each image. If you notice any issues with the translation of the text inside images, inform your coordinator and you will get the chance to proofread them too!
You can visualize the image in the
Preview section of Github (or on our website, open in another tab). Then, come back to the code section next to it for proofreading.Format recommendations
Here below you can find a few examples of format issues to pay attention to, when proofreading content in your target language.
- Pay attention to weird punctuation like
\*\*\, or**which might represent a bad rendering of the bold symbol. In the image below, you can see that the asterisks are only on the right of the word, which looks weird.
Thus, always check the original English text to see if a bold text is supposed to be there. In this case, just add two asterisks at the start of the word, to make it show correctly on the website. In fact, in the markdown language, to render the bold, you have to insert two asterisks
** both before and after the word/sentence (see example below).-
The same issues may happen with symbols like $ and
`. Make sure to check the original language file (often EN or FR) to see where these symbols are supposed to be. You can always ask the coordinator for assistance on this matter. -
If you find quotes, make sure to do some research online to find the right translation in your language. Quotes are usually inserted after the symbol
>.
Tutorial proofreading
If you decide to proofread tutorials, the coordinator will open a dedicated issue for the entire tutorial section. When you finish your task, you can document your progress by commenting in the issue with a list of the tutorials reviewed: this way, you create a clear tracking system for future reference, which is important because new content is added every month. You can see an example of this approach here.
Since new tutorials are added monthly, your branch may become outdated during the proofreading process. Some proofreaders have approached this problem by syncronizing the exact branch where they working: please NEVER do it! If you do, you risk losing all the progress you have made up until that moment!
Instead, you should finish proofreading the tutorials in your current fork first. Then, sync
dev, and create a new branch where you focus on proofreading the newly added tutorials (only the ones missing from your previous branch).In tutorials, there is a chance images might not be translated. Since most of the tutorials are originally written in French or English, you will probably find images that contain commands or instructions in their original language. Let's take an example from the tutorial on Sparrow in Dutch, by reporting both the text and the related image.
Verbinding maken met een openbaar knooppunt is heel eenvoudig. Klik op het tabblad "_Publieke server_".
As you can see, the image clearly points to
Public Server, in English, while the text mentions the expression _Publieke server_. In this case, there is a coherence issue, because the reader finds conflicting information when confronting the image with the text.To solve this matter, you can insert the command as it appears in the image (English or French), followed by the translation in your language within parentheses , as shown below:
Verbinding maken met een openbaar knooppunt is heel eenvoudig. Klik op het tabblad "_Public Server_" (Publieke server).
Quiz proofreading
Did you know you can also proofread the quiz questions in every course? For example, if you want to proofread the quizzes for BTC101 in IT, you could open a dedicated branch and follow this path: "courses" -> "BTC101" -> "quiz". There, you will find all the folders dedicated to each question, along with the related language file in yml format.
Once again, make sure you are in a dedicated branch that you open specifically for this purpose, and always inform the coordinator.
An important thing to keep in mind when proofreading this type of yml file is to avoid adding colons
: or quote signs inside the text . In fact, the colon is only used to separate key-value pairs like "wrong_answers" to the rest. You can see an example in the image below:After reviewing the question, make sure you change the "reviewed" status from "false" to "true," as shown in the image below. Make sure to keep these status words in English, no matter what language you are working on!
If the status line "reviewed:true" is missing, make sure to add it at the end of the quiz.
Glossary proofreading
Just like the quizzes, you can also proofread the glossary. The original glossary was written in French, so you will find sentences like: "In French, this expression can be translated into..."
In cases like this, please adapt the sentence to your target language or to English. For example, you might write "In English, this expression...".
If the title is left in English, you can adapt the sentence to your language: "In Swahili, this expression..."
Additionally, make sure to write titles in CAPITAL LETTERS.
The title and description of your PR
When you send your PR, it would be amazing if you named it using this format: [PROOFREADING] CONTENT NAME - LANGUAGE:
[PROOFREADING] BTC101 - ENGLISH
Besides, in the comment section of the PR, you can write "closes" + the number of the issue that the coordinator sent you when you started the proofreading task, preceded by
#.
For example, if you just sent a PR with the proofreading of cyp201 + quizzes, you can write "closes #2934".This way, the PR and the issue will be connected, and whoever reads the public Github repository can easily find information.
Other best practices
- If you need to search for specific words inside the text, you can click on
CTRL+Fand the find-replace section will appear. This part is very useful when you need to jump to a specific part of the text, or you need to replace specific words/sentences in batch, without scrolling the full content.
When using the "replace all" function, it's important to double-check the results to ensure that links haven't been altered as well. For instance, if you want to change the word "Bitcoin" to "Bitkoin" (which may be necessary in some languages), using the "replace all" function can efficiently update all instances in the text. However, be aware that this tool will also modify any links containing that word, potentially leading to redirection issues.
In the example below, the proofreader used the above function to replace "satoshi" with "satoshi(sats)", and also changed the link to a tutorial containing the word itself. As a consequence, the link became invalid.
Always double check all the hyperlinks in the text, to make sure they are correct.
- Following on the topic, if the author inserts a link referring to a Plan ₿ Academy course or tutorial (not inside parenthesis), the website will automatically create a "card" showing the related thumbnail. As a consequence, always make sure that you add a new line between the text and the link itself, otherwise you might see the following error on the website.
Conclusion
To sum up, being aware of the common proofreaders' mistakes can really help you improve your skills when checking content. It's easy to overlook things like context or consistency, and catching these errors can make a big difference.
Always keep in mind that a beginner may read these courses and tutorials, so it's our responsibility to ensure that they understand fully. As a proofreader, you are an educator!
Now you are ready to start proofreading courses, tutorials, quizzes, and glossary words. Stay tuned to start checking video transcripts as well!
Thank you for reading through this tutorial, and enjoy your proofreading journey!
Did this work well for you?
14
0
Author
This tutorial has been written by MariJ
Credits
This tutorial has been proofread by MariJJhodl
1/3Proofreading status
Even if this content is in its original language, human review is necessary to ensure its accuracy.
MariJJhodl2 028 sats1 014 satsEvery content on the platform is the result of a collaborative effort: each lesson, translation, and revision is made possible by the work of contributors. For this reason, we are always looking for proofreaders who can review our content in many languages. If you want to participate in the proofreading process, please reach out in our Telegram group and read our tutorial. We remind you that this content is open-source - licensed under CC BY-SA - so it can be freely shared and used, as long as the original source is credited.