Translating the Guide

If you are interested in translating The Alpha's Guide to the Galaxy into another language, this page outlines the process for doing so. Translated versions of the guide will be hosted on a subdomain (so for example, if one were to translate the Guide into German, the result would be hosted at https://de.thealphasguide.com).

The following assumes you know how to work with Git. If you don't but would still like to contribute translations, open an issue.

What to translate

The Guide is built via Hugo from a set of Markdown documents located in the content folder of the repository. Within each document is a header section that sets parameters such as the page title, and a body section containing the actual content of the page.

In general, you should restrict yourself to translating only:

• the title parameter in the header
• the body content of the page

In the rare case where the language to which you are translating does not typically use Arabic numerals, you may also translate the icon parameter in the header on certain pages which is used for numbering the top-level menu items.

Fonts

If the fonts used by the English version of the guide do not properly render the language to which you are translating, you can also modify static/css/overrides.css to change the font face to a web-safe font which renders the language properly. (If you are not familiar with CSS, assistance is available - open an issue.)

Images

You may provide localized replacements of images in the static/images if desired. If you do so, please ensure that the size of the image files is similar to (or smaller than) the original versions - sometimes editing and saving a new version of an image can result in a significant size difference if different compression options were selected.

Translation Feedback

You may also add a sentence to the note at the bottom of content/start/welcome.md telling people where they can provide feedback on the translation, in addition to the original guide.

How to translate

Begin by forking the repository (there is a button for this on the repository's home page). Next, create a new branch (not master) named translated- followed by the ISO 639-1 two-letter code for the language to which you are translating - to use the previous example, a German translation would use a branch named translated-de. (The rest of this page will use the text translated-XX - replace XX with the proper code.)

Now, on that branch, add new commits which replace the English source text with the appropriately translated text for your target language. This may include adding sentences as is necessary to clarify the meaning in the target language, but should seek to avoid significantly changing the overall content presented. (In particular, do not add editorial commentary.)

Submitting translations for publication

First, make sure that your branch is pushed to your fork on GitHub (the branch selector on your fork should display both master and your translated-XX branch).

If this is the first set of translations for the language in question, please open an issue with a link to your fork of the repository and the language to which you have translated the content. New languages require some extra legwork to set up the new subdomain before they can be added.

If this is an update to an existing language, open a pull request for your changes against the correct branch - make sure you're not asking for your changes to be merged into master.

Updates to the Guide

Changes made to the Guide will be committed onto master; if you wish to translate the updates, merge master into the translated-XX branch for the language in question. For new files, this will add the files into the translation branch in their English form, you can then create commits that replace them with the translated form. For changed files, the merge will most likely create a merge conflict; resolve the merge conflict to replace the new English text with a translated version and commit then result.

Please do not simply add new files to a translated-XX branch from scratch - always merge them in from master, then edit the file in-place. By editing the files in-place, we can easily mirror changes that don't require translation (such as modifying metadata) without having to do a translation pass.