⚙️ How to Translate Kernel Content¶

Translations can present a challenge. Our philosophy is that "content creators write the website", so the content folder therefore decides how the site is rendered, including translated content. This means, when you start to translate Kernel into your language, you'll need to create a brand new folder under the content directory and name it appropriately, i.e. en for English, es for Spanish, fr for French, ko for Korean etc.

We show translations on a per page basis, so as you translate the content, you'll need to then set the

hideLanguageSelector

field in your frontmatter to false, or simply do not include it (as it renders by default). This is cool because you can translate one page at a time instead of doing the whole project and then waiting months for reviews.

Because the content folder defines how the website renders, we need to keep a separate file for UI elements that are not found in any of the mdx files - like the text in the search box, or in the footer etc. Follow the structure in this file and make sure that each element there is translated.

Adding a new language in that file and a new directory in the content folder, named appropriately, should result in your language automatically appearing in the language selector for the pages you have translated.

Translator Responsibilities¶

The role of a translator is to create the initial translation from the original English documents.

Your responsibility is to:

• Translate as accurately as possible: All languages have their nuances, so there is some flexibility when changing the text to be more readable in a new language. Communicate with the rest of the team early and often in Slack. Don’t be afraid to ask others for advice.
• Decide which unique terms to translate: If there are any terms that do not have a direct equivalent in your language, please make sure to reach out to us in Slack and discuss the various options and their impact on the meaning.
• Provide accurate spelling and grammar.
• Be consistent: Ensure terms are translated uniformly across all documents.
• Maintain simplicity: Writing should be plain, simple, and accessible. Maintain contact with other translators as they work on documents. Be sure to agree on translated terms and other conventions.
• Format consistently: Ensure that translated documents retain original formatting.

Best Practices¶

• Use Markdown: All documents are formatted in Markdown. Use the cheatsheet to help you if you get lost.
• Maintain Original Formatting.
• Use a Markdown Editor: Editors like hackmd.io or VScode make working with Markdown more convenient.
• Keep hyperlinks as they are: Do not translate the actual URL. The editors will handle any necessary changes to links.
• Take notes: of the specific things you would like editors to keep in mind.
• Editor Tools: Feel free to use any software that helps find translation errors and improve writing. We encourage using tools that assist workflow but copying directly from a program will disqualify you from receiving a bounty and from future assignments. Please use them as an aide and not a substitute for your work.
• Communicate early and often: Join our Slack. We encourage reaching out to translators and reviewers for guidance.

Reviewer Responsibilities¶

The reviewer’s role is to ensure that translated documents meet both our formatting and writing style standards. Your responsibilities consist of proofreading documents for:

• Spelling and Grammar: Correct mistakes and typos if any are found.
• Language: Ensure that the writing style is in-line with Kernel terminology and best practices. For example, some languages translate the word "blockchain" while others keep the English spelling.
• Consistency: Ensure terms are translated uniformly across all documents.
• Simplicity: Our aim is to write plainly and simply. Maintain contact with translators as they work on documents. Be sure to agree on translated terms and other conventions.
• Formatting: Ensure that translated documents retain the original formatting.
• Adherence to the Kernel Style: A simple style must be maintained throughout all documents.
• Hyperlinks: Give extra attention to this task. Hyperlinks allow users to explore other important resources. Ensure all links are functioning properly and included where necessary. Hyperlinks fall into two general categories:
  • Links Between Translated Documents: If possible, ensure that the link goes to a page which has also been translated into that same language.
  • Links to Other Pages: Try to source a native language version for the link. For example, if a link leads to a Wikipedia page, it’s likely that a version of this page exists in the native language.